NAME

mt-libtt-intro — introduction to multi-thread safe ToolTalk library.

DESCRIPTION

To enable developers to write multithreaded applications, the Tt/tt_c.h header defines the following features:

    typedef enum tt_feature {


        _TT_FEATURE_MULTITHREADED = 1,  // Thread-safety


        _TT_FEATURE_LAST                // Enum end marker


    } Tt_feature;

Note that the TT_FEATURE_MULTITHREADED value is part of the libtt binary interface.

These features are accessed by calling code with corresponding #define constants:

#define TT_FEATURE_MULTITHREADED _TT_FEATURE_MULTITHREADED

Developers can write multi-threaded applications for ToolTalk without managing locks around ToolTalk resources explicitly in application code. Note that threading inside ToolTalk is not supported.

An extended version of the Xthreads.h thread API wrappers has been used so that multithreaded libtt is easily portable to various thread implementations.

A process-wide lock is used to protect internal libtt resources. Because few applications spend a significant amount of their time in libtt, a more fine-grained locking approach is not required.

A few ToolTalk global values, such as the default procid and the storage stack manipulated by the tt_mark and tt_release calls, must have a consistent state as seen by one thread across ToolTalk API calls. These global values have been made into thread-specific data. The calls described below are used to initialize this behavior and manipulate the new data. The other API calls have been modified to reference the thread-specific value instead of the process-wide value when a thread-specific value has been set for the current thread. If no thread-specific value has been set for the current thread, the process-wide value is used.

The following ToolTalk API calls implement support for multithreaded libtt:

tt_feature_enabled

Queries the ToolTalk service to see if a specified feature has been enabled. This allows libtt to determine if multithreaded execution has been enabled by the main program, and to modify its behavior accordingly.

tt_feature_required

Declares a feature to be required by the calling code. If the feature is available, tt_feature_required enables it. If the feature requires the ToolTalk service to perform some initialization (for example, TT_FEATURE_MULTITHREADED), the initialization is performed in this call. Some features (such as TT_FEATURE_MULTITHREADED) require this call to be made before calling tt_open.

tt_procid_session

Returns the identifier of the session in which a specified procid was opened.

tt_thread_procid

Returns the current default procid for the currently-active thread. If there is no default procid set for the thread, then the process default procid is returned.

tt_thread_procid_set

Sets the default procid for the currently active thread. The default procid is an implicit argument to most ToolTalk API calls.

tt_thread_session

Retrieves the default session identifier for the currently active thread. If there is no default session set for the currently-active thread, then the process default session identifier is returned.

tt_thread_session_set

Sets the default session identifier for the currently active thread. The ToolTalk service uses the initial user session as the default session and supports one session per procid. The application can make this call before it calls tt_open to specify which session it wants to connect to in the active thread.

Note that since the multithreaded feature may not be available on all platforms, the tt_feature_enabled function is provided to query for the existence of the feature. The intent is that even platforms that do not enable the multithreaded feature should implement the thread-related calls, returning TT_ERR_UNIMP. This allows a run-time check without unresolved symbol problems.

SEE ALSO

Tt/tt_c.h - Tttt_c(5), tt_feature_enabled(3), tt_feature_required(3), tt_procid_session(3), tt_thread_procid(3), tt_thread_procid_set(3), tt_thread_session(3), tt_thread_session(3)