critcl::iassoc(n) C Runtime In Tcl (CriTcl) critcl::iassoc(n)______________________________________________________________________________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 pack‐
ages 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 pro‐
vides 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 argu‐
ment, 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 identi‐
fiers 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 fail‐
ure.
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 ini‐
tialize.
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 inciden‐
tals, 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 documen‐
tation.
KEYWORDS
C code, Embedded C Code, Tcl Interp Association, code generator, com‐
pile & run, compiler, dynamic code generation, dynamic compilation,
generate package, linker, on demand compilation, on-the-fly compila‐
tion, singleton
CATEGORY
Glueing/Embedded C code
COPYRIGHT
Copyright (c) 2011-2015 Andreas Kupries
doc 1 critcl::iassoc(n)
