NAME

       critcl::iassoc - CriTcl Utilities: Tcl Interp Associations

SYNOPSIS

       package require Tcl  8.4

       package require critcl  ?3.1?

       package require critcl::iassoc  ?1?

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

_________________________________________________________________

DESCRIPTION

       Welcome  to the C Runtime In Tcl, CriTcl for short, a system to build C extension packages
       for Tcl on the fly, from C code embedded within Tcl scripts, for  all  who  wish  to  make
       their code go faster.

       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 {
              {
              /* Access to the data ... */
              icounter_data D = icounter (interp /* ... any declared arguments, here, none */);
              }
              }
              # 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-2012 Andreas Kupries