Provided by: critcl_3.1.17+dfsg-1_all 
NAME
critcl::cutil - CriTcl C-level Utilities
SYNOPSIS
package require Tcl 8.4
package require critcl ?2.1?
package require critcl::cutil ?0.1?
::critcl::cutil::alloc
::critcl::cutil::assertions ?enable?
::critcl::cutil::tracer ?enable?
type* ALLOC (type)
type* NALLOC (type, int n)
type* REALLOC (type* var, type, int n)
void FREE (type* var)
void ASSERT (expression, char* message
void ASSERT_BOUNDS (int index, int size)
void STOPAFTER(n)
void STREP (Tcl_Obj* o, char* s, int len)
void STREP_DS (Tcl_Obj* o, Tcl_DString* ds)
TRACE_ON
TRACE_OFF
TRACE_TAG_ON (identifier)
TRACE_TAG_OFF (identifier)
void TRACE_FUNC
void TRACE_TAG_FUNC (tag)
void TRACE_FUNC_VOID
void TRACE_TAG_FUNC_VOID (tag)
void TRACE_RETURN_VOID
void TRACE_TAG_RETURN_VOID (tag)
any TRACE_RETURN ( char* format, any x)
any TRACE_TAG_RETURN (tag, char* format, any x)
void TRACE ( char* format, ...)
void TRACE_TAG (tag, char* format, ...)
void TRACE_HEADER (int indent)
void TRACE_TAG_HEADER (tag, int indent)
void TRACE_CLOSER
void TRACE_TAG_CLOSER (tag)
void TRACE_ADD (const char* format, ...)
void TRACE_TAG_ADD (tag, const char* format, ...)
void TRACE_PUSH_SCOPE (const char* name)
void TRACE_PUSH_FUNC
void TRACE_PUSH_POP
TRACE_TAG_VAR (tag)
TRACE_RUN (code);
TRACE_DO (code);
TRACE_TAG_DO (tag, code);
_________________________________________________________________________________________________
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::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.
This package resides in the Core Package Layer of CriTcl.
+----------------+
|Applications |
| critcl |
| critcl::app |
+----------------+
*================*
|Core Packages |
| critcl |
| critcl::util |
*================*
+----------------+
|Support Packages|
| stubs::* |
| md5, platform |
| ... |
+----------------+
The reason for this is that the main critcl package makes use of the facilities for
narrative tracing when critcl::config trace is set, to instrument commands and procedures.
API
::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.
When run the header file "critcl_alloc.h" is directly made available to the
".critcl" file containing the command, and becomes available for use in #include
directives of companion C code declared via critcl::csources.
The macros definitions and their signatures are:
type* ALLOC (type)
type* NALLOC (type, int n)
type* REALLOC (type* var, type, int n)
void FREE (type* var)
The details of the semantics are explained in section Allocation.
The result of the command is an empty string.
::critcl::cutil::assertions ?enable?
This command provides a number C-preprocessor macros for the writing of assertions
in C code.
When invoked the header file "critcl_assert.h" is directly made available to the
".critcl" file containing the command, and becomes available for use in #include
directives of companion C code declared via critcl::csources.
The macro definitions and their signatures are
void ASSERT (expression, char* message);
void ASSERT_BOUNDS (int index, int size);
void STOPAFTER (int n);
void STREP (Tcl_Obj* o, char* s, int len);
void STREP_DS (Tcl_Obj* o, Tcl_DString* ds);
Note that these definitions are conditional on the existence of the macro CRITCL_ASSERT.
Without a 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.
For convenience this is controlled by enable. By default (false) the facility available,
but not active. Using true not only makes it available, but activates it as well.
The details of the semantics are explained in section Assertions.
The result of the command is an empty string.
::critcl::cutil::tracer ?enable?
This command provides a number C-preprocessor macros for tracing C-level internals.
When invoked the header file "critcl_trace.h" is directly made available to the
".critcl" file containing the command, and becomes available for use in #include
directives of companion C code declared via critcl::csources. Furthermore the ".c"
file containing the runtime support is added to the set of C companion files
The macro definitions and their signatures are
/* (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);
Note that these definitions are conditional on the existence of the macro CRITCL_TRACER.
Without a 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.
For convenience this is controlled by enable. By default (false) the facility available,
but not active. Using true not only makes it available, but activates it as well.
Further note that the command critcl::config now accepts a boolean option trace. Setting
it activates enter/exit tracing in all commands based on critcl::cproc, with proper
printing of arguments and results. This implicitly activates the tracing facility in
general.
The details of the semantics are explained in section Tracing
The result of the command is an empty string.
ALLOCATION
type* ALLOC (type)
This macro allocates a single element of the given type and returns a pointer to
that memory.
type* NALLOC (type, int n)
This macro allocates n elements of the given type and returns a pointer to that
memory.
type* REALLOC (type* var, type, int n)
This macro expands or shrinks the memory associated with the C variable var of type
type to hold 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 var
allows the user to validate the new pointer before trying to use it.
void FREE (type* var)
This macro releases the memory referenced by the pointer variable var.
ASSERTIONS
void ASSERT (expression, char* message
This macro tests the expression and panics if it does not hold. The specified
message is used as part of the panic. The message has to be a static string, it
cannot be a variable.
void ASSERT_BOUNDS (int index, int size)
This macro ensures that the index is in the range 0 to size-1.
void STOPAFTER(n)
This macro throws a panic after it is called n times. Note, each separate instance
of the macro has its own counter.
void STREP (Tcl_Obj* o, char* s, int len)
This macro properly sets the string representation of the Tcl object o to a copy of
the string s, expected to be of length len.
void STREP_DS (Tcl_Obj* o, Tcl_DString* ds)
This macro properly sets the string representation of the Tcl object o to a copy of
the string held by the DString ds.
TRACING
All output is printed to stdout.
TRACE_ON
TRACE_OFF
TRACE_TAG_ON (identifier)
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.
For example:
TRACE_TAG_ON (lexer_in);
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.
void TRACE_FUNC
void TRACE_TAG_FUNC (tag)
void TRACE_FUNC_VOID
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 (__func__), forcing users to have a
C99 compiler..
The tracer's runtime maintains a stack of active functions and expects that
function return is signaled by either TRACE_RETURN, TRACE_RETURN_VOID, or the
equivalent forms taking a tag.
void TRACE_RETURN_VOID
void TRACE_TAG_RETURN_VOID (tag)
Use these macros instead of
return
to 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.
any TRACE_RETURN ( char* format, any x)
any TRACE_TAG_RETURN (tag, char* format, any x)
Use this macro instead of
return x
to non-void function. Beyond returning from the function with value x this also
signals the same to the tracer's runtime, popping the last entered function from
its stack of active functions. The format is expected to be a proper formatting
string for printf and analogues, able to stringify x.
void TRACE ( char* format, ...)
void TRACE_TAG (tag, char* format, ...)
This macro is the trace facilities' equivalent of printf, printing arbitrary data
under the control of the format.
The printed text is closed with a newline, and indented as per the stack of active
functions.
void TRACE_HEADER (int indent)
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.
void TRACE_CLOSER
void TRACE_TAG_CLOSER (tag)
This is the low-level macro which prints the end of a trace line.
void TRACE_ADD (const char* format, ...)
void TRACE_TAG_ADD (tag, const char* format, ...)
This is the low-level macro which adds formatted data to the line.
void TRACE_PUSH_SCOPE (const char* name)
void TRACE_PUSH_FUNC
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.
TRACE_TAG_VAR (tag)
Helper macro converting from a tag identifier to the name of the underlying status
variable.
TRACE_RUN (code);
Conditionally insert the code at compile time when the tracing facility is
activated.
TRACE_DO (code);
TRACE_TAG_DO (tag, code);
Insert the 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.
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 documentation.
KEYWORDS
C code, Embedded C Code, code generator, compile & run, compiler, dynamic code generation,
dynamic compilation, generate package, linker, on demand compilation, on-the-fly
compilation
CATEGORY
Glueing/Embedded C code
COPYRIGHT
Copyright (c) 2011-2015 Andreas Kupries