The blob utilities are intended to allow users to convert Swift blobs into C-style pointer and length arguments for C/C++/Fortran leaf functions.

The blob utilities are:

  1. SWIG-wrapped C functions, thus accessible from Tcl functions called by Swift

  2. Tcl functions to provide convenience functionality

For usage examples, see the Swift/T Leaf Function Guide.

The blob utilities may also be used by user C leaf functions. Simply include turbine/include/blob.h.

This documentation is generated from blob.h and blob.tcl by maint/doc.sh. The C functions are implemented in blob.c.

Blobs may be represented in Tcl by either:

  1. A SWIG-generated turbine_blob* (called a turbine_blob)

  2. A Tcl [list pointer length] (called a Tcl blob). These are used by STC and the Turbine Data (TD) system.

Struct turbine_blob

Simple struct for variable-length data blob.

This data type is represented by SWIG in Tcl as a regular pointer- you can pass it in and out of functions, display it, etc.

typedef struct
{
  void* pointer;
  int length;
} turbine_blob;

Based on this struct, SWIG will generate the following Tcl functions, assuming blob is a turbine_blob*:

new_turbine_blob

Returns a fresh turbine_blob*.

delete_turbine_blob blob

free() the blob. Cf. blobutils_destroy().

turbine_blob_pointer_set blob p

Set blob→pointer=p, where p is a void*.

turbine_blob_pointer_get blob

Returns blob→pointer, a void*.

turbine_blob_length_set blob i

Set blob→pointer=i, where i is an integer.

turbine_blob_length_get blob

Returns blob→length, an int.

Functions

Pointers and sizes

Functions for turbine_blob creation, memory allocation/deallocation, pointer arithmetic, and sizeof().

blobutils_create pointer length

Create a turbine_blob from a long integer representing the pointer and the length.

blobutils_create_ptr pointer length

Create a turbine_blob from the pointer and the length.

blobutils_malloc length

Allocate memory (not a blob) of given size.

blobutils_free pointer

Call free() on the given pointer.

blobutils_destroy

Deallocate a blob and frees the data pointer.

blobutils_ptr_add pointer offset

Return the result of adding offset to pointer.

blobutils_sizeof_ptr

Obtain sizeof(void*)

blobutils_sizeof_int

Obtain sizeof(int)

blobutils_sizeof_int32

Obtain sizeof(int32)

blobutils_sizeof_float

Obtain sizeof(double). (In Swift/T, all floats are 64-bit)

Casts

Cast functions for simple SWIG type transformations. Not all possible type pairs are yet implemented. In our naming scheme, if a type is not given, void* is assumed.

blobutils_cast_to_ptr i

Integer to void*.

blobutils_cast_int64_to_ptr i

Integer (64-bit) to void*.

blobutils_cast_to_ptrptr p

void* to void**.

blobutils_cast_to_string p

void* to char**.

blobutils_cast_to_char_ptrptr p

void* to char**.

blobutils_cast_string_to_ptrptr s

char* to void*.

blobutils_cast_to_int p

void* to int.

blobutils_cast_to_long p

void* to long.

blobutils_cast_to_long_long p

void* to long long.

blobutils_cast_to_int64 p

void* to int64_t.

blobutils_cast_int_to_int_ptr i

int to int*.

blobutils_cast_int_to_const_int_ptr i

int to const int*.

blobutils_cast_int_to_dbl_ptr i

int to double*.

blobutils_cast_int_to_const_dbl_ptr i

int to const double*.

blobutils_cast_long_to_int_ptr i

long to int*.

blobutils_cast_long_to_const_int_ptr i

long to const int*.

blobutils_cast_long_to_dbl_ptr i

long to double*.

blobutils_cast_long_to_const_dbl_ptr i

long to const double*.

blobutils_cast_to_int_ptr p

void* to int*.

blobutils_cast_to_int64_ptr p

void* to int64_t*.

blobutils_cast_to_int32_ptr p

void* to int32_t*.

blobutils_cast_to_dbl_ptr p

void* to double*.

Array manipulation

These functions treat their inputs as arrays and do manipulation.

blobutils_zeroes_float p n

Set all n entries of double array p to 0.0.

blobutils_get_ptr pointer index

Assume blob is array of void* - do array lookup. That is, return pointer[index].

blobutils_set_ptr pointer index p

Assume blob is array of void* - do array store. That is, set pointer[index]=p.

blobutils_get_float pointer index

Assume blob is array of double- do array lookup. That is, return pointer[index].

blobutils_set_float p index d

Assume blob is array of double - do array store. That is, set p[index]=d.

blobutils_get_int pointer index

Assume blob is array of int - do array lookup. That is, return pointer[index].

blobutils_get_int32 pointer index

Assume blob is array of int32_t - do array lookup. That is, return pointer[index].

blobutils_set_int pointer index i

Assume blob is array of int - do array store. That is, set pointer[index]=i.

I/O

Blob I/O functions.

blobutils_write output blob

Write blob blob to file with name given in output. Returns true on success, else false.

blobutils_read input blob

Read blob blob from file with name given in output. Returns true on success, else false.

String utilities

Functions for string operations.

blobutils_strdup s

Duplicate s.

HDF utilities

Functions for HDF operations.

blobutils_hdf_write output dataset blob

Write blob to HDF file with name given in output in dataset dataset. Returns true on success, else false.

Tcl convenience functions

These functions operate on Tcl blobs.

blob_size_async out blob

Turbine rule to obtain the size of TD blob in TD out

blob_size blob

Obtain the size of blob

blob_null blob

Store NULL in the blob

string2blob

Turbine rule to translate TD blob input into TD string result

blob2string

Turbine rule to translate TD string input in TD blob result

blob2floats

Obtain doubles from blob, return as dictionary mapping integer index to double

matrix_from_blob_fortran_impl blob m n

Obtain doubles from blob, return as dictionary mapping integer indices to double in Fortran order, m is the number of rows, n is the number of columns

floats2blob out in

Store Tcl floats from dict into blob

floats2blob out in

Store Tcl ints from dict into blob

floats2blob n

Store n zeroes into new blob

turbine_run_output_blob dummy blob

Store blob as turbine_run() result, dummy is unused

blob_debug_ints blob

Print blob of ints

blob_fmt blob

Return printable blob metadata (TD, pointer, length) as string

blob_fmt blob

Print blob metadata (TD, pointer, length) via blob_fmt

blob_dict_to_int_array

Input: L: a Tcl dict of integer→integer indexed from 0.
Output: a SWIG pointer (int*) to a fresh array of int.

blob_string_list_to_char_ptr_ptr

Convert Tcl list of strings to char**.
Helpful for passing data into C-style argc/argv interfaces.

blob_string_dict_to_char_ptr_ptr d

Input: A Tcl dict of integer→string indexed from 0.
Output: A SWIG pointer (char**) to the C strings.
Helpful for passing data into C-style argc/argv interfaces.

blob_strings_to_char_ptr_ptr d

Deprecated alias for blob_string_dict_to_char_ptr_ptr.

blob_string_list_to_argv program L argv_name

Convert Tcl list of strings L to char**.
Helpful for passing data into C-style argc/argv interfaces.
Puts result (char**) in argv_name.
program: Program name as string (i.e., argv[0]).
L: list of strings (i.e., argv[1]…argv[argc-1]).
Returns argc.