NAME

SYNOPSIS

package require critcl ?3.1.18?

::critcl::has-resulttype name

::critcl::resulttype name body ?ctype?

::critcl::resulttype name = origname

::critcl::has-argtype name

::critcl::argtype name body ?ctype? ?ctypefun?

::critcl::argtype name = origname

::critcl::argtypesupport name code ?guard?

::critcl::argtyperelease name code

DESCRIPTION

This document is a breakout of the descriptions for the predefined argument- and result-types usable with the critcl::cproc command, as detailed in the reference manpage for the critcl package, plus the information on how to extend the predefined set with custom types. The breakout was made to make this information easier to find (toplevel document vs. having to search the large main reference).

Its intended audience are developers wishing to write Tcl packages with embedded C code.

STANDARD ARGUMENT TYPES

Critcl type | C type         | Tcl type  | Notes
----------- | -------------- | --------- | ------------------------------
Tcl_Interp* | Tcl_Interp*    | n/a       | Special, only first
----------- | -------------- | --------- | ------------------------------
Tcl_Obj*    | Tcl_Obj*       | Any       | Read-only
object      |                |           | Alias of Tcl_Obj* above
list        | critcl_list    | List      | Read-only
----------- | -------------- | --------- | ------------------------------
char*       | const char*    | Any       | Read-only, string rep
pstring     | critcl_pstring | Any       | Read-only
bytes       | critcl_bytes   | ByteArray | Read-only
----------- | -------------- | --------- | ------------------------------
int         | int            | Int       |
long        | long           | Long      |
wideint     | Tcl_WideInt    | WideInt   |
double      | double         | Double    |
float       | float          | Double    |
----------- | -------------- | --------- | ------------------------------
X > 0       |                |           | For X in int ... float above.
X >= 0      |                |           | C types as per the base type X.
X < 0       |                |           | Allowed argument values are
X <= 0      |                |           | restricted as per the shown
X > 1       |                |           | relation
X >= 1      |                |           |
X < 1       |                |           | This is not a general mechanism
X <= 1      |                |           | open to other values. Only 0/1.
----------- | -------------- | --------- | ------------------------------
boolean     | int            | Boolean   |
bool        |                |           | Alias of boolean above
----------- | -------------- | --------- | ------------------------------
bytearray   |                |           | DEPRECATED
rawchar     |                |           | DEPRECATED
rawchar*    |                |           | DEPRECATED
double*     |                |           | DEPRECATED
float*      |                |           | DEPRECATED
int*        |                |           | DEPRECATED
void*       |                |           | DEPRECATED

Tcl_Interp*

Attention: This is a special argument type. It can only be used by the first argument of a function. Any other argument using it will cause critcl to throw an error.

When used, the argument will contain a reference to the current interpreter that the function body may use. Furthermore the argument will not be an argument of the Tcl command for the function.

This is useful when the function has to do more than simply returning a value. Examples would be setting up error messages on failure, or querying the interpreter for variables and other data.

Tcl_Obj*

object

The function takes an argument of type Tcl_Obj*. No argument checking is done. The Tcl level word is passed to the argument as-is. Note that this value must be treated as read-only (except for hidden changes to its intrep, i.e. shimmering).

pstring

The function takes an argument of type critcl_pstring containing the original Tcl_Obj* reference of the Tcl argument, plus the length of the string and a pointer to the character array.

typedef struct critcl_pstring {
    Tcl_Obj*    o;
    const char* s;
    int         len;
} critcl_pstring;

Note the const. The string is read-only. Any modification can have arbitrary effects, from pulling out the rug under the script because of string value and internal representation not matching anymore, up to crashes anytime later.

list

The function takes an argument of type critcl_list containing the original Tcl_Obj* reference of the Tcl argument, plus the length of the Tcl list and a pointer to the array of the list elements.

typedef struct critcl_list {
    Tcl_Obj*        o;
    Tcl_Obj* const* v;
    int             c;
} critcl_list;

The Tcl argument must be convertible to List, an error is thrown otherwise.

Note the const. The list is read-only. Any modification can have arbitrary effects, from pulling out the rug under the script because of string value and internal representation not matching anymore, up to crashes anytime later.

bytearray

rawchar*

rawchar

The function takes an argument of type char*. The Tcl argument must be convertible to ByteArray, an error is thrown otherwise. Note that the length of the ByteArray is not passed to the function, making this type not very usable.

Attention: These types are considered DEPRECATED. It is planned to remove their documentation in release 3.2, and their implementation in release 3.3. Their deprecation can be undone if good use cases are shown.

bytes

This is the new and usable ByteArray type.

The function takes an argument of type critcl_bytes containing the original Tcl_Obj* reference of the Tcl argument, plus the length of the byte array and a pointer to the byte data.

typedef struct critcl_bytes {
    Tcl_Obj*             o;
    const unsigned char* s;
    int                len;
} critcl_list;

The Tcl argument must be convertible to ByteArray, an error is thrown otherwise.

Note the const. The bytes are read-only. Any modification can have arbitrary effects, from pulling out the rug under the script because of string value and internal representation not matching anymore, up to crashes anytime later.

char*

The function takes an argument of type const char*. The string representation of the Tcl argument is passed in.

Note the const. The string is read-only. Any modification can have arbitrary effects, from pulling out the rug under the script because of string value and internal representation not matching anymore, up to crashes anytime later.

double

The function takes an argument of type double. The Tcl argument must be convertible to Double, an error is thrown otherwise.

double > 0

double >= 0

double < 0

double <= 0

double > 1

double >= 1

double < 1

double <= 1

These are variants of double above, restricting the argument value to the shown relation. An error is thrown for Tcl arguments outside of the specified range. Note: This is not a general range specification syntax. Only the listed types exist.

float

The function takes an argument of type float. The Tcl argument must be convertible to Double, an error is thrown otherwise.

float > 0

float >= 0

float < 0

float <= 0

float > 1

float >= 1

float < 1

float <= 1

These are variants of float above, restricting the argument value to the shown relation. An error is thrown for Tcl arguments outside of the specified range. Note: This is not a general range specification syntax. Only the listed types exist.

boolean

bool

The function takes an argument of type int. The Tcl argument must be convertible to Boolean, an error is thrown otherwise.

channel

The function takes an argument of type Tcl_Channel. The Tcl argument must be convertible to type Channel, an error is thrown otherwise. The channel is further assumed to be already registered with the interpreter.

unshared-channel

This type is an extension of channel above. All of the information above applies.

Beyond that the channel must not be shared by multiple interpreters, an error is thrown otherwise.

take-channel

This type is an extension of unshared-channel above. All of the information above applies.

Beyond that the code removes the channel from the current interpreter without closing it, and disables all pre-existing event handling for it.

With this the function takes full ownership of the channel in question, taking it away from the interpreter invoking it. It is then responsible for the lifecycle of the channel, up to and including closing it.

Should the system the function is a part of wish to return control of the channel back to the interpeter it then has to use the result type return-channel. This will undo the registration changes made by this argument type. Note however that the removal of pre-existing event handling done here cannot be undone.

Attention Removal from the interpreter without closing the channel is effected by incrementing the channel's reference count without providing an interpreter, before decrementing the same for the current interpreter. This leaves the overall reference count intact without causing Tcl to close it when it is removed from the interpreter structures. At this point the channel is effectively a globally-owned part of the system not associated with any interpreter.

The complementary result type then runs this sequence in reverse. And if the channel is never returned to Tcl either the function or the system it is a part of have to unregister the global reference when they are done with it.

int

The function takes an argument of type int. The Tcl argument must be convertible to Int, an error is thrown otherwise.

int > 0

int >= 0

int < 0

int <= 0

int > 1

int >= 1

int < 1

int <= 1

These are variants of int above, restricting the argument value to the shown relation. An error is thrown for Tcl arguments outside of the specified range. Note: This is not a general range specification syntax. Only the listed types exist.

long

The function takes an argument of type long int. The Tcl argument must be convertible to Long, an error is thrown otherwise.

long > 0

long >= 0

long < 0

long <= 0

long > 1

long >= 1

long < 1

long <= 1

These are variants of long above, restricting the argument value to the shown relation. An error is thrown for Tcl arguments outside of the specified range. Note: This is not a general range specification syntax. Only the listed types exist.

wideint

The function takes an argument of type Tcl_WideInt. The Tcl argument must be convertible to WideInt, an error is thrown otherwise.

wideint > 0

wideint >= 0

wideint < 0

wideint <= 0

wideint > 1

wideint >= 1

wideint < 1

wideint <= 1

These are variants of wideint above, restricting the argument value to the shown relation. An error is thrown for Tcl arguments outside of the specified range. Note: This is not a general range specification syntax. Only the listed types exist.

void*

double*

float*

int*

The function takes an argument of the same-named C type. The Tcl argument must be convertible to ByteArray, an error is thrown otherwise. The bytes in the ByteArray are then re-interpreted as the raw representation of a single C pointer of the given type which is then passed as argument to the function. In other words, this is for Tcl values somehow holding raw C pointers, i.e. memory addresses.

Attention: These types are considered DEPRECATED. It is planned to remove their documentation in release 3.2, and their implementation in release 3.3. Their deprecation can be undone if good use cases are shown.

STANDARD RESULT TYPES

Critcl type   | C type         | Tcl type  | Notes
------------- | -------------- | --------- | ------------------------------
void          | n/a            | n/a       | Always OK. Body sets result
ok            | int            | n/a       | Result code. Body sets result
------------- | -------------- | --------- | ------------------------------
int           | int            | Int       |
boolean       |                |           | Alias of int above
bool          |                |           | Alias of int above
long          | long           | Long      |
wideint       | Tcl_WideInt    | WideInt   |
double        | double         | Double    |
float         | float          | Double    |
------------- | -------------- | --------- | ------------------------------
char*         | char*          | String    | Makes a copy
vstring       |                |           | Alias of char* above
const char*   | const char*    |           | Behavior of char* above
------------- | -------------- | --------- | ------------------------------
string        |                | String    | Freeable string set directly
              |                |           | No copy is made
dstring       |                |           | Alias of string above
------------- | -------------- | --------- | ------------------------------
              |                |           | For all below: Null is ERROR
              |                |           | Body has to set any message
Tcl_Obj*      | Tcl_Obj*       | Any       | refcount --
object        |                |           | Alias of Tcl_Obj* above
Tcl_Obj*0     |                | Any       | refcount unchanged
object0       |                |           | Alias of Tcl_Obj*0 above
------------- | -------------- | --------- | ------------------------------
known-channel | Tcl_Channel    | String    | Assumes to already be registered
new-channel   | Tcl_Channel    | String    | New channel, will be registered

Tcl_Obj*

object

If the returned Tcl_Obj* is NULL, the Tcl return code is TCL_ERROR and the function should set an error mesage [https://www.tcl-lang.org/man/tcl/TclLib/SetResult.htm] as the interpreter result. Otherwise, the returned Tcl_Obj* is set as the interpreter result.

Note that setting an error message requires the function body to have access to the interpreter the function is running in. See the argument type Tcl_Interp* for the details on how to make that happen.

Note further that the returned Tcl_Obj* should have a reference count greater than 0. This is because the converter decrements the reference count to release possession after setting the interpreter result. It assumes that the function incremented the reference count of the returned Tcl_Obj*. If a Tcl_Obj* with a reference count of 0 were returned, the reference count would become 1 when set as the interpreter result, and immediately thereafter be decremented to 0 again, causing the memory to be freed. The system is then likely to crash at some point after the return due to reuse of the freed memory.

Tcl_Obj*0

object0

Like Tcl_Obj* except that this conversion assumes that the returned value has a reference count of 0 and does not decrement it. Returning a value whose reference count is greater than 0 is therefore likely to cause a memory leak.

Note that setting an error message requires the function body to have access to the interpreter the function is running in. See the argument type Tcl_Interp* for the details on how to make that happen.

new-channel

A String Tcl_Obj holding the name of the returned Tcl_Channel is set as the interpreter result. The channel is further assumed to be new, and therefore registered with the interpreter to make it known.

known-channel

A String Tcl_Obj holding the name of the returned Tcl_Channel is set as the interpreter result. The channel is further assumed to be already registered with the interpreter.

return-channel

This type is a variant of new-channel above. It varies slightly from it in the registration sequence to be properly complementary to the argument type take-channel. A String Tcl_Obj holding the name of the returned Tcl_Channel is set as the interpreter result. The channel is further assumed to be new, and therefore registered with the interpreter to make it known.

char*

vstring

A String Tcl_Obj holding a copy of the returned char* is set as the interpreter result. If the value is allocated then the function itself and the extension it is a part of are responsible for releasing the memory when the data is not in use any longer.

const char*

Like char* above, except that the returned string is const-qualified.

string

dstring

The returned char* is directly set as the interpreter result without making a copy. Therefore it must be dynamically allocated via Tcl_Alloc. Release happens automatically when the Interpreter finds that the value is not required any longer.

double

float

The returned double or float is converted to a Double Tcl_Obj and set as the interpreter result.

boolean

bool

The returned int value is converted to an Int Tcl_Obj and set as the interpreter result.

int

The returned int value is converted to an Int Tcl_Obj and set as the interpreter result.

long

The returned long int value is converted to a Long Tcl_Obj and set as the interpreter result.

wideint

The returned Tcl_WideInt value is converted to a WideInt Tcl_Obj and set as the interpreter result.

ok

The returned int value becomes the Tcl return code. The interpreter result is left untouched and can be set by the function if desired. Note that doing this requires the function body to have access to the interpreter the function is running in. See the argument type Tcl_Interp* for the details on how to make that happen.

void

The function does not return a value. The interpreter result is left untouched and can be set by the function if desired.

ADVANCED: ADDING TYPES

To get around this limitation the commands in this section enable users of critcl to extend the set of argument and result types understood by critcl::cproc. In other words, they allow them to define their own, custom, types.

::critcl::has-resulttype name

This command tests if the named result-type is known or not. It returns a boolean value, true if the type is known and false otherwise.

::critcl::resulttype name body ?ctype?

This command defines the result type name, and associates it with the C code doing the conversion (body) from C to Tcl. The C return type of the associated function, also the C type of the result variable, is ctype. This type defaults to name if it is not specified.

If name is already declared an error is thrown. Attention! The standard result type void is special as it has no accompanying result variable. This cannot be expressed by this extension command.

The body's responsibility is the conversion of the functions result into a Tcl result and a Tcl status. The first has to be set into the interpreter we are in, and the second has to be returned.

The C code of body is guaranteed to be called last in the wrapper around the actual implementation of the cproc in question and has access to the following environment:

As examples here are the definitions of two standard result types:

    resulttype int {
	Tcl_SetObjResult(interp, Tcl_NewIntObj(rv));
	return TCL_OK;
    }
    resulttype ok {
	/* interp result must be set by cproc body */
	return rv;
    } int

::critcl::resulttype name = origname

This form of the resulttype command declares name as an alias of result type origname, which has to be defined already. If this is not the case an error is thrown.

::critcl::has-argtype name

This command tests if the named argument-type is known or not. It returns a boolean value, true if the type is known and false otherwise.

::critcl::argtype name body ?ctype? ?ctypefun?

This command defines the argument type name, and associates it with the C code doing the conversion (body) from Tcl to C. ctype is the C type of the variable to hold the conversion result and ctypefun is the type of the function argument itself. Both types default to name if they are the empty string or are not provided.

If name is already declared an error is thrown.

body is a C code fragment that converts a Tcl_Obj* into a C value which is stored in a helper variable in the underlying function.

body is called inside its own code block to isolate local variables, and the following items are in scope:

As examples, here are the definitions of two standard argument types:

    argtype int {
	if (Tcl_GetIntFromObj(interp, @@, &@A) != TCL_OK) return TCL_ERROR;
    }
    argtype float {
	double t;
	if (Tcl_GetDoubleFromObj(interp, @@, &t) != TCL_OK) return TCL_ERROR;
	@A = (float) t;
    }

::critcl::argtype name = origname

This form of the argtype command declares name as an alias of argument type origname, which has to be defined already. If this is not the case an error is thrown.

::critcl::argtypesupport name code ?guard?

This command defines a C code fragment for the already defined argument type name which is inserted before all functions using that type. Its purpose is the definition of any supporting C types needed by the argument type. If the type is used by many functions the system ensures that only the first of the multiple insertions of the code fragment is active, and the others disabled. The guard identifier is normally derived from name, but can also be set explicitly, via guard. This latter allows different custom types to share a common support structure without having to perform their own guarding.

::critcl::argtyperelease name code

This command defines a C code fragment for the already defined argument type name which is inserted whenever the worker function of a critcl::cproc returns to the shim. It is the responsibility of this fragment to unconditionally release any resources the critcl::argtype conversion code allocated. An example of this are the variadic types for the support of the special, variadic args argument to critcl::cproc's. They allocate a C array for the collected arguments which has to be released when the worker returns. This command defines the C code for doing that.

EXAMPLES

    proc math {x y z} {
        return [expr {(sin($x)*rand())/$y**log($z)}]
    }

    critcl::cproc math {double x double y double z} double {
        double up   = rand () * sin (x);
        double down = pow(y, log (z));
        return up/down;
    }

    critcl::argtype Marpa_Symbol_ID     = int
    critcl::argtype Marpa_Rule_ID       = int
    critcl::argtype Marpa_Rule_Int      = int
    critcl::argtype Marpa_Rank          = int
    critcl::argtype Marpa_Earleme       = int
    critcl::argtype Marpa_Earley_Set_ID = int
    ...
    method sym-rank: proc {
        Marpa_Symbol_ID sym
        Marpa_Rank      rank
    } Marpa_Rank {
        return marpa_g_symbol_rank_set (instance->grammar, sym, rank);
    }
    ...

    critcl::argtype yaml_sequence_style_t {
        if (!encode_sequence_style (interp, @@, &@A)) return TCL_ERROR;
    }
    ...
    critcl::ccode {
        static const char* ty_block_style_names [] = {
            "any", "block", "flow", NULL
        };
        static int
        encode_sequence_style (Tcl_Interp* interp, Tcl_Obj* style,
                               yaml_sequence_style_t* estyle)
        {
            int value;
            if (Tcl_GetIndexFromObj (interp, style, ty_block_style_names,
                                     "sequence style", 0, &value) != TCL_OK) {
                return 0;
            }
            *estyle = value;
            return 1;
        }
    }
    ...
    method sequence_start proc {
        pstring anchor
        pstring tag
        int implicit
        yaml_sequence_style_t style
    } ok {
        /* Syntax: <instance> seq_start <anchor> <tag> <implicit> <style> */
        ...
    }
    ...

    critcl::emap::def yaml_sequence_style_t {
        any   0
        block 1
        flow  2
    }

    critcl::argtype image {
        if (crimp_get_image_from_obj (interp, @@, &@A) != TCL_OK) {
            return TCL_ERROR;
        }
    } crimp_image* crimp_image*
    ...
        set map [list <<type>> $type]
        critcl::argtype image_$type [string map $map {
            if (crimp_get_image_from_obj (interp, @@, &@A) != TCL_OK) {
                return TCL_ERROR;
            }
            if (@A->itype != crimp_imagetype_find ("crimp::image::<<type>>")) {
                Tcl_SetObjResult (interp,
                                  Tcl_NewStringObj ("expected image type <<type>>",
                                                    -1));
                return TCL_ERROR;
            }
        }] crimp_image* crimp_image*
    ...

    critcl::argtype pstring {
        @A.s = Tcl_GetStringFromObj(@@, &(@A.len));
        @A.o = @@;
    } critcl_pstring critcl_pstring
    critcl::argtypesupport pstring {
        typedef struct critcl_pstring {
            Tcl_Obj*    o;
            const char* s;
            int         len;
        } critcl_pstring;
    }

    critcl::argtype pstring {
        @A = (critcl_pstring*) ckalloc(sizeof(critcl_pstring));
        @A->s = Tcl_GetStringFromObj(@@, &(@A->len));
        @A->o = @@;
    } critcl_pstring* critcl_pstring*
    critcl::argtypesupport pstring {
        typedef struct critcl_pstring {
            Tcl_Obj*    o;
            const char* s;
            int         len;
        } critcl_pstring;
    }
    critcl::argtyperelease pstring {
        ckfree ((char*)) @A);
    }

    critcl::resulttype KTcl_Obj* {
        if (rv == NULL) { return TCL_ERROR; }
        Tcl_SetObjResult(interp, rv);
        /* No refcount adjustment */
        return TCL_OK;
    } Tcl_Obj*

    critcl::resulttype XnStatus {
        if (rv != XN_STATUS_OK) {
            Tcl_AppendResult (interp, xnGetStatusString (rv), NULL);
            return TCL_ERROR;
        }
        return TCL_OK;
    }
    critcl::resulttype XnDepthPixel {
        if (rv == ((XnDepthPixel) -1)) {
            Tcl_AppendResult (interp,
                              "Inheritance error: Not a depth generator",
                              NULL);
            return TCL_ERROR;
        }
        Tcl_SetObjResult (interp, Tcl_NewIntObj (rv));
        return TCL_OK;
    }

AUTHORS

BUGS, IDEAS, FEEDBACK

KEYWORDS

CATEGORY

COPYRIGHT

Copyright (c) Jean-Claude Wippler
Copyright (c) Steve Landers
Copyright (c) 2011-2018 Andreas Kupries