Cheap Threads: Macros and Typedefs

Macros and Typedefs

Macros

Of the macros defined in the ct.h header file, the first four are defined merely for convenience:

CT_OKAY - return code signifying success
CT_ERROR - return code signifying failure
CT_TRUE - typical boolean
CT_FALSE - typical boolean

Three others define certain operating parameters within Cheap Threads. For a given application it may be useful to modify their values. In each case, ct.h defines the macro only if it is not already defined. Most compilers provide some mechanism to define a macro outside of the source code.

CT_PRIORITY_MAX -- The highest priority level, i.e. the level designating the lowest priority. In other words, this macro defines a number that is one less than the number of priority levels (since the indexing starts at zero).
CT_DEFAULT_COUNTDOWN -- The number of threads run by the scheduler, by default, before it scrunches the queues. At run time the application may override this default by calling ct_set_countdown(). For more details see the discussion of the scheduler internals.
CT_MSG_BUF_LEN - The maximum number of bytes of data that a message may carry without allocating additional memory. For Embedded Cheap Threads, this is the maximum length of message data. For more details see the discussion of messaging.

Macro for Timeouts

The code implementing timeouts is disabled by default, in order to avoid incurring the overhead in applications that don't use timeouts. If you want to use timeouts, compile Cheap Threads with the macro CT_TIMEOUT defined.

Macro for ct_return()

The code implementing the ct_return function is disabled by default, in order to avoid incurring the overhead in applications that don't use it. If you want to use ct_return(), compile Cheap Threads with the macro CT_RETURN defined.

Macros for Embedded Cheap Threads

Several macros apply only when using Embedded Cheap Threads to avoid dynamic memory allocation, as described elsewhere. In each case the source code defines a value only if no value has been defined elsewhere, as by a compiler option.

CT_MAX_THREADS (#defined in ectalloc.c) -- The maximum number of threads that may be defined at one time, including threads that are asleep while waiting for a message. Default: 10
CT_MAX_EVENTS (#defined in ectalloc.c) -- The maximum number of events that a single thread may send during one cycle of the scheduler. A distributed or broadcast event counts only once, not once for each recipient. Default: 20
CT_MAX_MSGNODES (#defined in ectalloc.c) -- The maximum number of pending messages that may be enqueued to all threads at a given time, after they are delivered but before they are dequeued. A single message distributed or broadcast to multiple threads counts multiple times. Default: 20
CT_MAX_SUBS (#defined in ectsubsc.c) -- The maximum number of message subscriptions that may be in effect at one time. There is one subscription for each message type to which each thread is subscribed. Default: 20

Each of these macros defines the size of a static array of objects that may be used and reused at run time. The default values are arbitrary and may not be appropriate for a given application. It is the developer's job to analyze the application carefully to determine appropriate values.

See also the description of CT_MSG_BUF_LEN in the preceding section.

Typedefs

Several of the Cheap Threads functions take function pointers as parameters. Since the syntax of function pointers is rather clumsy and cryptic, the ct.h header provides typedefs for several kinds of function pointer:

Ct_error_reporter - accepts a const char * and returns void. Role: to issue an error message. Installed by ct_install_error_reporter(), and invoked by ct_report_error().
Ct_step_function - accepts a void * and returns an int. Role: to do whatever a thread does when it runs. Installed by ct_create_thread(), and invoked by the scheduler when a thread runs.
Ct_destructor - accepts a void * and returns void. Role: to release resources owned by an expiring thread. Installed by ct_create_thread(), and invoked by the scheduler when the thread expires, or when the scheduler terminates.
Ct_user_exit - accepts a void * and returns an int. Role: defined by the application. Installed by ct_install_pre_function() or ct_install_post_function(), and invoked by the scheduler immediately before or after running each thread, respectively.

Home