libuproc  1.2.0
libuproc Documentation

Table of Contents

Error handling

Unless noted otherwise, functions return the following values:

In case of failure, functions set a global (thread-local if compiled with OpenMP) error code and message, see error.h for details on how to retrieve the error.

Types and objects

If you browse the Modules, page, you will see quite a bunch of "modules" called "object uproc_..." or "struct uproc_...". These are the types defined by libuproc and they usually follow the conventions described below.

Opaque object types

Opaque object types are usually defined as forward declarations to structs hidden in the implementation (to ease API compatibility across different versions):

typedef ... uproc_OBJECT;

Creation

Objects of such type are created by calling the corresponding uproc_OBJECT_create function, e.g.:

Destruction

Every non-NULL pointer returned by uproc_OBJECT_create should be passed to the corresponding uproc_OBJECT_destroy:

Passing NULL to any of the uproc_OBJECT_destroy functions is a no-op (and will NOT result in a nullpointer dereference).

Iterator object types

Certain objects are iterators (the ones whose OBJECT part ends in "iter"). These have a function uproc_OBJECT_next that returns 0 if an item was produced, 1 if the iterator is exhausted or -1 on error.

Struct types

Initialization

For a struct type struct uproc_STRUCT, if there is an initializer macro called UPROC_STRUCT_INITIALIZER present, this initializer can be used when defining objects of that type. Alternatively, such a struct can be initialized by passing a pointer to it to the coresponding uproc_OBJECT_init function.

Freeing struct members

If the struct contains pointers to allocated storage, they can (and should) be freed using uproc_STRUCT_free. The values of affected members will be set to NULL.

Deep-copying

If there is a corresponding uproc_STRUCT_copy function, it should be used to deep-copy the struct.

Multithreading and reentrancy

Except for the following, all parts of the library are reentrant:

When using either of uproc_stdin, uproc_stdout_gz or uproc_stderr_gz for the first time, all of them are initialized. A race condition would result in a (minor) memory leak.

The Error handling mechanisms are only tested with OpenMP and might not behave correctly if used in conjunction with other threading implementations.