File: critcl_cutil.man

package info (click to toggle)
critcl 3.3.1%2Bdfsg-1
  • links: PTS, VCS
  • area: main
  • in suites: sid, trixie
  • size: 9,680 kB
  • sloc: ansic: 41,058; tcl: 12,090; sh: 7,230; pascal: 3,456; asm: 3,058; ada: 1,681; cpp: 1,001; cs: 879; makefile: 333; perl: 104; xml: 95; f90: 10
file content (413 lines) | stat: -rw-r--r-- 14,370 bytes parent folder | download
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
[vset VERSION 0.3]
[comment {-*- tcl -*- doctools manpage}]
[manpage_begin critcl::cutil 3tcl [vset VERSION]]
[include include/module2.inc]
[titledesc {CriTcl - C-level Utilities}]
[require Tcl 8.6]
[require critcl [opt 3.2]]
[require critcl::cutil [opt [vset VERSION]]]
[description]
[para]
[include include/welcome.inc]
[para]

This document is the reference manpage for the [package critcl::cutil]
package. This package encapsulates a number of C-level utilites for
easier writing of memory allocations, assertions, and narrative tracing
and provides convenience commands to make these utilities accessible
to critcl projects.

Its intended audience are mainly developers wishing to write Tcl
packages with embedded C code.
[para]

This package resides in the Core Package Layer of CriTcl.
[para][image arch_core][para]

The reason for this is that the main [package critcl] package makes
use of the facilities for narrative tracing when
[cmd {critcl::config trace}] is set, to instrument commands and
procedures.

[comment {= = == === ===== ======== ============= =====================}]
[section API]

[list_begin definitions]
[comment {* * ** *** ***** ******** ************* *********************}]
[call [cmd ::critcl::cutil::alloc]]

This command provides a number C-preprocessor macros which make the
writing of memory allocations for structures and arrays of structures
easier.

[para] When run the header file [file critcl_alloc.h] is directly made
available to the [file .critcl] file containing the command, and
becomes available for use in [cmd {#include}] directives of companion
C code declared via [cmd critcl::csources].

[para] The macros definitions and their signatures are:

[example {
    type* ALLOC (type)
    type* ALLOC_PLUS (type, int n)
    type* NALLOC (type, int n)
    type* REALLOC (type* var, type, int n)
    void  FREE (type* var)

    void STREP    (Tcl_Obj* o, char* s, int len);
    void STREP_DS (Tcl_Obj* o, Tcl_DString* ds);
    void STRDUP   (varname, char* str);
}]

[para] The details of the semantics are explained in section
[sectref Allocation].

[para] The result of the command is an empty string.

[comment {* * ** *** ***** ******** ************* *********************}]
[call [cmd ::critcl::cutil::assertions] [opt [arg enable]]]

This command provides a number C-preprocessor macros for the writing
of assertions in C code.

[para] When invoked the header file [file critcl_assert.h] is directly
made available to the [file .critcl] file containing the command, and
becomes available for use in [cmd {#include}] directives of companion
C code declared via [cmd critcl::csources].

[para] The macro definitions and their signatures are

[example {
    void ASSERT (expression, char* message);
    void ASSERT_BOUNDS (int index, int size);

    void STOPAFTER (int n);
}]

[para] Note that these definitions are conditional on the existence of
the macro [const CRITCL_ASSERT]. 

Without a [cmd {critcl::cflags -DCRITCL_ASSERT}] all assertions in the
C code are quiescent and not compiled into the object file. In other
words, assertions can be (de)activated at will during build time, as
needed by the user.

[para] For convenience this is controlled by [arg enable]. By default
([const false]) the facility available, but not active.

Using [const true] not only makes it available, but activates it as
well.

[para] The details of the semantics are explained in section
[sectref Assertions].

[para] The result of the command is an empty string.

[comment {* * ** *** ***** ******** ************* *********************}]
[call [cmd ::critcl::cutil::tracer] [opt [arg enable]]]

This command provides a number C-preprocessor macros for tracing
C-level internals.

[para] When invoked the header file [file critcl_trace.h] is directly
made available to the [file .critcl] file containing the command, and
becomes available for use in [cmd {#include}] directives of companion
C code declared via [cmd critcl::csources]. Furthermore the [file .c]
file containing the runtime support is added to the set of C companion
files

[para] The macro definitions and their signatures are

[example {
    /* (de)activation of named logical streams.
     * These are declarators, not statements.
     */

    TRACE_ON;
    TRACE_OFF;
    TRACE_TAG_ON  (tag_identifier);
    TRACE_TAG_OFF (tag_identifier);

    /*
     * Higher level trace statements (convenience commands)
     */

    void TRACE_FUNC   (const char* format, ...);
    void TRACE_FUNC_VOID;
    any  TRACE_RETURN (const char* format, any x);
    void TRACE_RETURN_VOID;
    void TRACE (const char* format, ...);

    /*
     * Low-level trace statements the higher level ones above
     * are composed from. Scope management and output management.
     */

    void TRACE_PUSH_SCOPE (const char* scope);
    void TRACE_PUSH_FUNC;
    void TRACE_POP;

    void TRACE_HEADER (int indent);
    void TRACE_ADD (const char* format, ...);
    void TRACE_CLOSER;

    /*
     * Convert tag to the underlying status variable.
     */

    TRACE_TAG_VAR (tag)

    /*
     * Conditional use of arbitrary code.
     */

    TRACE_RUN (code);
    TRACE_DO (code);
    TRACE_TAG_DO (code);
}]

[para] Note that these definitions are conditional on the existence of
the macro [const CRITCL_TRACER]. 

Without a [cmd {critcl::cflags -DCRITCL_TRACER}] all trace
functionality in the C code is quiescent and not compiled into the
object file. In other words, tracing can be (de)activated at will
during build time, as needed by the user.

[para] For convenience this is controlled by [arg enable]. By default
([const false]) the facility available, but not active.

Using [const true] not only makes it available, but activates it as
well.

Further note that the command [cmd critcl::config] now accepts a
boolean option [const trace]. Setting it activates enter/exit tracing
in all commands based on [cmd critcl::cproc], with proper printing of
arguments and results. This implicitly activates the tracing facility
in general.

[para] The details of the semantics are explained in section
[sectref Tracing]

[para] The result of the command is an empty string.

[list_end]

[comment {= = == === ===== ======== ============= =====================}]
[section Allocation]

[list_begin definitions]
[comment {* * ** *** ***** ******** ************* *********************}]
[call [cmd {type* ALLOC (type)}]]

This macro allocates a single element of the given [arg type] and
returns a pointer to that memory.

[call [cmd {type* ALLOC_PLUS (type, int n)}]]

This macro allocates a single element of the given [arg type], plus an
additional [arg n] bytes after the structure and returns a pointer to
that memory.

[para] This is for variable-sized structures of. An example of such
could be a generic list element structure which stores management
information in the structure itself, and the value/payload immediately
after, in the same memory block.

[call [cmd {type* NALLOC (type, int n)}]]

This macro allocates [arg n] elements of the given [arg type] and
returns a pointer to that memory.

[call [cmd {type* REALLOC (type* var, type, int n)}]]

This macro expands or shrinks the memory associated with the C
variable [arg var] of type [arg type] to hold [arg n] elements of the
type. It returns a pointer to that memory.

Remember, a reallocation may move the data to a new location in memory
to satisfy the request. Returning a pointer instead of immediately
assigning it to the [arg var] allows the user to validate the new
pointer before trying to use it.

[call [cmd {void FREE (type* var)}]]

This macro releases the memory referenced by the pointer variable
[arg var].

[comment {* * ** *** ***** ******** ************* *********************}]
[call [cmd {void STREP (Tcl_Obj* o, char* s, int len)}]]

This macro properly sets the string representation of the Tcl object
[arg o] to a copy of the string [arg s], expected to be of length
[arg len].

[comment {* * ** *** ***** ******** ************* *********************}]
[call [cmd {void STREP_DS (Tcl_Obj* o, Tcl_DString* ds)}]]

This macro properly sets the string representation of the Tcl object
[arg o] to a copy of the string held by the [type DString] [arg ds].

[comment {* * ** *** ***** ******** ************* *********************}]
[call [cmd {void STRDUP (varname, char* str)}]]

This macro duplicates the string [arg str] into the heap and stores
the result into the named [type char*] variable [arg var].

[list_end]

[comment {= = == === ===== ======== ============= =====================}]
[section Assertions]

[list_begin definitions]
[comment {* * ** *** ***** ******** ************* *********************}]
[call [cmd {void ASSERT (expression, char* message}]]

This macro tests the [arg expression] and panics if it does not hold.
The specified [arg message] is used as part of the panic.
The [arg message] has to be a static string, it cannot be a variable.

[comment {* * ** *** ***** ******** ************* *********************}]
[call [cmd {void ASSERT_BOUNDS (int index, int size)}]]

This macro ensures that the [arg index] is in the
range [const 0] to [const {size-1}].

[comment {* * ** *** ***** ******** ************* *********************}]
[call [cmd {void STOPAFTER(n)}]]

This macro throws a panic after it is called [arg n] times.
Note, each separate instance of the macro has its own counter.

[list_end]

[comment {= = == === ===== ======== ============= =====================}]
[section Tracing]

All output is printed to [const stdout].

[list_begin definitions]

[comment {* * ** *** ***** ******** ************* *********************}]
[call [cmd TRACE_ON]]
[call [cmd TRACE_OFF]]
[call [cmd {TRACE_TAG_ON  (identifier)}]]
[call [cmd {TRACE_TAG_OFF (identifier)}]]

These "commands" are actually declarators, for use outside of
functions. They (de)activate specific logical streams, named either
explicitly by the user, or implicitly, refering to the current file.

[para] For example:
[para][example {
    TRACE_TAG_ON (lexer_in);
}]

[para] All high- and low-level trace commands producing output have
the controlling tag as an implicit argument. The scope management
commands do not take tags.


[comment {* * ** *** ***** ******** ************* *********************}]
[call [cmd {void TRACE_FUNC}]]
[call [cmd {void TRACE_TAG_FUNC (tag)}]]
[call [cmd {void TRACE_FUNC_VOID}]]
[call [cmd {void TRACE_TAG_FUNC_VOID (tag)}]]

Use these macros at the beginning of a C function to record entry into
it. The name of the entered function is an implicit argument
([var __func__]), forcing users to have a C99 compiler..

[para] The tracer's runtime maintains a stack of active functions and
expects that function return is signaled by either [fun TRACE_RETURN],
[fun TRACE_RETURN_VOID], or the equivalent forms taking a tag.

[comment {* * ** *** ***** ******** ************* *********************}]
[call [cmd {void TRACE_RETURN_VOID}]]
[call [cmd {void TRACE_TAG_RETURN_VOID (tag)}]]

Use these macros instead of [example {return}] to return from a void
function. Beyond returning from the function this also signals the
same to the tracer's runtime, popping the last entered function from
its stack of active functions.

[comment {* * ** *** ***** ******** ************* *********************}]
[call [cmd {any TRACE_RETURN     (     char* format, any x)}]]
[call [cmd {any TRACE_TAG_RETURN (tag, char* format, any x)}]]

Use this macro instead of [example {return x}] to return from a
non-void function.

Beyond returning from the function with value [arg x] this also
signals the same to the tracer's runtime, popping the last entered
function from its stack of active functions.

The [arg format] is expected to be a proper formatting string for
[fun printf] and analogues, able to stringify [arg x].

[comment {* * ** *** ***** ******** ************* *********************}]
[call [cmd {void TRACE     (     char* format, ...)}]]
[call [cmd {void TRACE_TAG (tag, char* format, ...)}]]

This macro is the trace facilities' equivalent of [fun printf],
printing arbitrary data under the control of the [arg format].

[para] The printed text is closed with a newline, and indented as per
the stack of active functions.

[comment {* * ** *** ***** ******** ************* *********************}]
[call [cmd {void TRACE_HEADER (int indent)}]]
[call [cmd {void TRACE_TAG_HEADER (tag, int indent)}]]

This is the low-level macro which prints the beginning of a trace
line. This prefix consists of physical location (file name and line
number), if available, indentation as per the stack of active scopes
(if activated), and the name of the active scope.

[comment {* * ** *** ***** ******** ************* *********************}]
[call [cmd {void TRACE_CLOSER}]]
[call [cmd {void TRACE_TAG_CLOSER (tag)}]]

This is the low-level macro which prints the end of a trace
line.

[comment {* * ** *** ***** ******** ************* *********************}]
[call [cmd {void TRACE_ADD          (const char* format, ...)}]]
[call [cmd {void TRACE_TAG_ADD (tag, const char* format, ...)}]]

This is the low-level macro which adds formatted data to the line.

[comment {* * ** *** ***** ******** ************* *********************}]
[call [cmd {void TRACE_PUSH_SCOPE (const char* name)}]]
[call [cmd {void TRACE_PUSH_FUNC}]]
[call [cmd {void TRACE_PUSH_POP}]]

These are the low-level macros for scope management. The first two
forms push a new scope on the stack of active scopes, and the last
forms pops the last scope pushed.

[comment {* * ** *** ***** ******** ************* *********************}]
[call [cmd {TRACE_TAG_VAR (tag)}]]

Helper macro converting from a tag identifier to the name of the
underlying status variable.

[comment {* * ** *** ***** ******** ************* *********************}]
[call [cmd {TRACE_RUN (code);}]]

Conditionally insert the [arg code] at compile time when the tracing
facility is activated.

[comment {* * ** *** ***** ******** ************* *********************}]
[call [cmd {TRACE_DO (code);}]]
[call [cmd {TRACE_TAG_DO (tag, code);}]]

Insert the [arg code] at compile time when the tracing facility is
activated, and execute the same when either the implicit tag for the
file or the user-specified tag is active.

[list_end]

[comment {= = == === ===== ======== ============= =====================}]
[include include/feedback2.inc]
[manpage_end]