NAME

       critcl::iassoc - CriTcl Utilities: Tcl Interp Associations

SYNOPSIS

       package require Tcl  8.4

       package require critcl  ?3.1?

       package require critcl::iassoc  ?1.1?

       ::critcl::iassoc::def name arguments struct constructor destructor

_________________________________________________________________________________________________

DESCRIPTION

       C  Runtime In Tcl, or CriTcl , is a system for compiling C code embedded in Tcl on the fly
       and either loading the resulting objects into Tcl for immediate use or packaging them  for
       distribution.  Use CriTcl to improve performance by rewriting in C those routines that are
       performance bottlenecks.

       This document is the reference  manpage  for  the  critcl::iassoc  package.  This  package
       provides convenience commands for advanced functionality built on top of the critcl core.

       With  it  a  user  wishing  to  associate  some  data  with  a  Tcl  interpreter via Tcl's
       Tcl_(Get|Set)AssocData() APIs can now concentrate  on  the  data  itself,  while  all  the
       necessary boilerplate around it is managed by this package.

       Its  intended audience are mainly developers wishing to write Tcl packages with embedded C
       code.

       This package resides in the Core Package Layer of CriTcl.

       +----------------+
       |Applications    |
       | critcl         |
       | critcl::app    |
       +----------------+

       *================*
       |Core Packages   |
       | critcl         |
       | critcl::util   |
       *================*

       +----------------+
       |Support Packages|
       | stubs::*       |
       | md5, platform  |
       |  ...           |
       +----------------+

API

       ::critcl::iassoc::def name arguments struct constructor destructor
              This command defines a C function with the given name which provides  access  to  a
              structure associated with a Tcl interpreter.

              The C code code fragment struct defines the elements of said structure, whereas the
              fragments constructor and destructor are C code blocks executed to  initialize  and
              release  any  dynamically allocated parts of this structure, when needed. Note that
              the structure itself is managed by the system.

              The new function takes a Tcl_Interp* pointer  refering  to  the  interpreter  whose
              structure we wish to obtain as the first argument, plus the specified arguments and
              returns a pointer to the associated structure, of type "name_data" (see below).

              The arguments are a dictionary-like list of  C  types  and  identifiers  specifying
              additional  arguments for the accessor function, and, indirectly, the constructor C
              code block. This is useful for the supplication of initialization  values,  or  the
              return of more complex error information in case of a construction failure.

              The C types associated with the structure are derived from name, with "name_data__"
              the type of the structure itself, and "name_data" representing  a  pointer  to  the
              structure.  The C code blocks can rely on the following C environments:

              constructor

                     data   Pointer to the structure (type: name_data) to initialize.

                     interp Pointer  to the Tcl interpreter (type: Tcl_Interp*) the new structure
                            will be associated with.

                     error  A C code label the constructor can jump to should it have to signal a
                            construction  failure. It is the responsibility of the constructor to
                            release any fields already initialized before jumping to this label.

                     ...    The names of the constructor arguments specified with arguments.

              destructor

                     data   Pointer to the structure being released.

                     interp Pointer to the Tcl interpreter the structure belonged to.

EXAMPLE

       The example shown below is the specification of a simple  interpreter-associated  counter.
       The  full  example,  with  meta  data and other incidentals, can be found in the directory
       "examples/queue" of the critcl source distribution/repository.

              package require Tcl 8.4
              package require critcl 3.1

              critcl::buildrequirement {
                  package require critcl::iassoc
              }

              critcl::iassoc::def icounter {} {
                  int counter; /* The counter variable */
              } {
                  data->counter = 0;
              } {
                  /* Nothing to release */
              }

              critcl::ccode {
                  ... function (...)
                  {
                       /* Access to the data ... */
                       icounter_data D = icounter (interp /* ... any declared arguments, here, none */);
                 ... D->counter ...
                  }
              }
              # or, of course, 'cproc's, 'ccommand's etc.

              package provide icounter 1

AUTHORS

       Andreas Kupries

BUGS, IDEAS, FEEDBACK

       This document, and the package it describes,  will  undoubtedly  contain  bugs  and  other
       problems.   Please  report such at https://github.com/andreas-kupries/critcl.  Please also
       report any ideas for enhancements you may have for either package and/or documentation.

KEYWORDS

       C code, Embedded C Code, Tcl Interp Association, code generator, compile & run,  compiler,
       dynamic  code  generation,  dynamic  compilation,  generate  package,  linker,  on  demand
       compilation, on-the-fly compilation, singleton

CATEGORY

       Glueing/Embedded C code

COPYRIGHT

       Copyright (c) 2011-2018 Andreas Kupries