critcl::iassoc(n)

📦 version 3.3.1, in alpine 3.24

🎀 critcl::iassoc(n) 🎀 — CriTcl · Code Gen · Tcl Interp Associations

okay so bestie, welcome to the C Runtime In Tcl (everyone calls it CriTcl for short) 💖 — it's the whole system for embedding and running C code from inside your Tcl scripts over at [http://core.tcl-lang.org/tcl](http://core.tcl-lang.org/tcl).

This page right here is the reference manpage for critcl::iassoc, and it's literally a little convenience package that gives you the advanced stuff built on top of the critcl core. ✨

✨ 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 💅

So here's the vibe check: you wanna associate some data with a Tcl interpreter using Tcl's Tcl_(Get|Set)AssocData() APIs. Normally that means you're drowning in boilerplate 😭 — but with this package you get to concentrate on the data itself, and all the annoying boilerplate around it is managed for you by the package. Obsessed. 🫶

Who's this for? Mainly developers who want to write Tcl packages with embedded C code. iykyk.

This package lives in the Core Package Layer of CriTcl, which looks like this:

+----------------+
|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. Main character energy fr fr 👑

  • The C code fragment struct defines the elements of said structure.
  • 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. 💀 (not you, bestie — the system handles it)

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. ⚠️ (like, literally — clean up your own mess before you bail)
  • ... — 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. (iconic of it, honestly) Please report such at [https://github.com/andreas-kupries/critcl](https://github.com/andreas-kupries/critcl). Please also report any ideas for enhancements you may have for either package and/or documentation — they wanna hear it. 🫶

⭐ 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 (c) 2011-2024 Andreas Kupries

💖 that's the whole page bestie, go forth and associate some data with your interpreters, you've got this 💖

and that's a wrap!! 🎀 this lil doc shipped as doc, version 1.2, under the name critcl::iassoc(n) — mwah, catch u on the next manpage 🌈✨

📦 where this page comes from