NAME

       critcl::iassoc - CriTcl - Code Gen - Tcl Interp Associations

SYNOPSIS

       package require Tcl  8.6

       package require critcl  ?3.2?

       package require critcl::iassoc  ?1.2?

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

________________________________________________________________________________________________________________

DESCRIPTION

       Be  welcome  to the C Runtime In Tcl (short: CriTcl), a system for embedding and using C code from within
       Tcl [http://core.tcl-lang.org/tcl] scripts.

       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.6
              package require critcl 3.2

              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-2024 Andreas Kupries

doc                                                    1.2                                  critcl::iassoc(3tcl)