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

doc                                                    1.1                                  critcl::iassoc(3tcl)