GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages
critcl::iassoc(n) C Runtime In Tcl (CriTcl) critcl::iassoc(n)


critcl::iassoc - CriTcl Utilities: Tcl Interp Associations

package require Tcl 8.4

package require critcl ?3.1?

package require critcl::iassoc ?1.1?

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


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  |
|  ...           |
+----------------+

::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.

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

Andreas Kupries

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.

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

Glueing/Embedded C code

Copyright (c) 2011-2018 Andreas Kupries
1.1 doc

Search for    or go to Top of page |  Section n |  Main Index

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with ManDoc.