3
<title>critcl::iassoc - C Runtime In Tcl (CriTcl)</title>
4
<style type="text/css"><!--
17
DIV.doctools H1,DIV.doctools H2 {
22
font-family: sans-serif;
25
background: transparent;
45
UL.toc,UL.toc UL, UL.toc UL UL {
46
font: normal 12pt/14pt sans-serif;
49
LI.section, LI.subsection {
57
font-family: monospace;
61
padding-bottom: 0.5ex;
69
border: 1px solid black;
71
UL.requirements LI, UL.syntax LI {
80
border: 1px solid black;
87
border-top: 1px solid black;
91
border-bottom: 1px solid black;
95
<! -- Generated from file '/home/aku/Projects/Packages/Critcl/dev-master/embedded/www/files/critcl_iassoc.html' by tcllib/doctools with format 'html'
97
<! -- Copyright © 2011-2012 Andreas Kupries
99
<! -- CVS: $Id$ critcl::iassoc.n
101
<body><div class="doctools">
103
<a href="../toc.html">Table Of Contents</a>
104
| <a href="../index.html">Keyword Index</a>
106
<h1 class="title">critcl::iassoc(n) 1 doc "C Runtime In Tcl (CriTcl)"</h1>
107
<div id="name" class="section"><h2><a name="name">Name</a></h2>
108
<p>critcl::iassoc - CriTcl Utilities: Tcl Interp Associations</p>
110
<div id="toc" class="section"><h2><a name="toc">Table Of Contents</a></h2>
112
<li class="section"><a href="#toc">Table Of Contents</a></li>
113
<li class="section"><a href="#synopsis">Synopsis</a></li>
114
<li class="section"><a href="#section1">Description</a></li>
115
<li class="section"><a href="#section2">API</a></li>
116
<li class="section"><a href="#section3">Example</a></li>
117
<li class="section"><a href="#section4">Authors</a></li>
118
<li class="section"><a href="#section5">Bugs, Ideas, Feedback</a></li>
119
<li class="section"><a href="#keywords">Keywords</a></li>
120
<li class="section"><a href="#category">Category</a></li>
121
<li class="section"><a href="#copyright">Copyright</a></li>
124
<div id="synopsis" class="section"><h2><a name="synopsis">Synopsis</a></h2>
125
<div class="synopsis">
126
<ul class="requirements">
127
<li>package require <b class="pkgname">Tcl 8.4</b></li>
128
<li>package require <b class="pkgname">critcl <span class="opt">?3.1?</span></b></li>
129
<li>package require <b class="pkgname">critcl::iassoc <span class="opt">?1?</span></b></li>
132
<li><a href="#1"><b class="cmd">::critcl::iassoc::def</b> <i class="arg">name</i> <i class="arg">arguments</i> <i class="arg">struct</i> <i class="arg">constructor</i> <i class="arg">destructor</i></a></li>
136
<div id="section1" class="section"><h2><a name="section1">Description</a></h2>
137
<p>Welcome to the <i class="term">C Runtime In Tcl</i>, <i class="term"><a href="critcl_pkg.html">CriTcl</a></i> for short, a
138
system to build C extension packages for Tcl on the fly, from C code
139
embedded within Tcl scripts, for all who wish to make their code go
141
<p>This document is the reference manpage for the <b class="package">critcl::iassoc</b>
142
package. This package provides convenience commands for advanced
143
functionality built on top of the critcl core.</p>
144
<p>With it a user wishing to associate some data with a Tcl
145
interpreter via Tcl's <b class="function">Tcl_(Get|Set)AssocData()</b> APIs can now
146
concentrate on the data itself, while all the necessary boilerplate
147
around it is managed by this package.</p>
148
<p>Its intended audience are mainly developers wishing to write
149
Tcl packages with embedded C code.</p>
150
<p>This package resides in the Core Package Layer of CriTcl.</p>
151
<p><img alt="arch_core" src="../image/arch_core.png"></p>
153
<div id="section2" class="section"><h2><a name="section2">API</a></h2>
154
<dl class="definitions">
155
<dt><a name="1"><b class="cmd">::critcl::iassoc::def</b> <i class="arg">name</i> <i class="arg">arguments</i> <i class="arg">struct</i> <i class="arg">constructor</i> <i class="arg">destructor</i></a></dt>
156
<dd><p>This command defines a C function with the given <i class="arg">name</i> which
157
provides access to a structure associated with a Tcl interpreter.</p>
158
<p>The C code code fragment <i class="arg">struct</i> defines the elements of
159
said structure, whereas the fragments <i class="arg">constructor</i> and
160
<i class="arg">destructor</i> are C code blocks executed to initialize and release
161
any dynamically allocated parts of this structure, when needed. Note
162
that the structure itself is managed by the system.</p>
163
<p>The new function takes a <b class="const">Tcl_Interp*</b> pointer refering
164
to the interpreter whose structure we wish to obtain as the first
165
argument, plus the specified <i class="arg">arguments</i> and returns a pointer to
166
the associated structure, of type "<i class="arg">name</i>_data" (see below).</p>
167
<p>The <i class="arg">arguments</i> are a dictionary-like list of C types and
168
identifiers specifying additional arguments for the accessor function,
169
and, indirectly, the <i class="arg">constructor</i> C code block. This is useful
170
for the supplication of initialization values, or the return of more
171
complex error information in case of a construction failure.</p>
172
<p>The C types associated with the structure are derived from
173
<i class="arg">name</i>, with "<i class="arg">name</i>_data__" the type of the structure itself,
174
and "<i class="arg">name</i>_data" representing a pointer to the structure.
175
The C code blocks can rely on the following C environments:</p>
176
<dl class="definitions">
177
<dt><i class="arg">constructor</i></dt>
178
<dd><dl class="definitions">
179
<dt><b class="variable">data</b></dt>
180
<dd><p>Pointer to the structure (type: <i class="arg">name</i>_data) to
182
<dt><b class="variable">interp</b></dt>
183
<dd><p>Pointer to the Tcl interpreter (type: Tcl_Interp*)
184
the new structure will be associated with.</p></dd>
186
<dd><p>A C code label the constructor can jump to should it have
187
to signal a construction failure. It is the responsibility of the
188
constructor to release any fields already initialized before jumping
189
to this label.</p></dd>
191
<dd><p>The names of the constructor arguments specified with
192
<i class="arg">arguments</i>.</p></dd>
194
<dt><i class="arg">destructor</i></dt>
195
<dd><dl class="definitions">
196
<dt><b class="variable">data</b></dt>
197
<dd><p>Pointer to the structure being released.</p></dd>
198
<dt><b class="variable">interp</b></dt>
199
<dd><p>Pointer to the Tcl interpreter the structure
200
belonged to.</p></dd>
205
<div id="section3" class="section"><h2><a name="section3">Example</a></h2>
206
<p>The example shown below is the specification of a simple interpreter-associated
207
counter. The full example, with meta data and other incidentals, can be found
208
in the directory "<b class="file">examples/queue</b>" of the critcl source
209
distribution/repository.</p>
210
<pre class="example">
211
package require Tcl 8.4
212
package require critcl 3.1
213
critcl::buildrequirement {
214
package require critcl::iassoc
216
critcl::iassoc::def icounter {} {
217
int counter; /* The counter variable */
219
data->counter = 0;
221
/* Nothing to release */
226
/* Access to the data ... */
227
icounter_data D = icounter (interp /* ... any declared arguments, here, none */);
228
... D->counter ...
231
# or, of course, 'cproc's, 'ccommand's etc.
232
package provide icounter 1
235
<div id="section4" class="section"><h2><a name="section4">Authors</a></h2>
236
<p>Andreas Kupries</p>
238
<div id="section5" class="section"><h2><a name="section5">Bugs, Ideas, Feedback</a></h2>
239
<p>This document, and the package it describes, will undoubtedly contain
240
bugs and other problems.
241
Please report such at <a href="https://github.com/andreas-kupries/critcl">https://github.com/andreas-kupries/critcl</a>.
242
Please also report any ideas for enhancements you may have for either
243
package and/or documentation.</p>
245
<div id="keywords" class="section"><h2><a name="keywords">Keywords</a></h2>
246
<p><a href="../index.html#key8">C code</a>, <a href="../index.html#key3">Embedded C Code</a>, <a href="../index.html#key15">Tcl Interp Association</a>, <a href="../index.html#key6">code generator</a>, <a href="../index.html#key0">compile & run</a>, <a href="../index.html#key10">compiler</a>, <a href="../index.html#key1">dynamic code generation</a>, <a href="../index.html#key2">dynamic compilation</a>, <a href="../index.html#key9">generate package</a>, <a href="../index.html#key4">linker</a>, <a href="../index.html#key5">on demand compilation</a>, <a href="../index.html#key7">on-the-fly compilation</a>, <a href="../index.html#key14">singleton</a></p>
248
<div id="category" class="section"><h2><a name="category">Category</a></h2>
249
<p>Glueing/Embedded C code</p>
251
<div id="copyright" class="section"><h2><a name="copyright">Copyright</a></h2>
252
<p>Copyright © 2011-2012 Andreas Kupries</p>
added
removed
embedded/www/files/critcl_iassoc.html
