MT-LIBTT-INTRO(4)

📦
version 2.5.3 · 2 versions
, in nixos 26.05

💖 NAME 💖

Bestie, this is mt-libtt-intro — introduction to multi-thread safe ToolTalk library. It's the special file page for the multi-thread safe libtt intro, and we're doing this with group-chat energy but zero missing facts, periodt. ✨

✨ 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;

Quick heads-up: the TT_FEATURE_MULTITHREADED value is part of the libtt binary interface, so that's not just a cute little enum name 🫶.

Calling code gets at these features through matching #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. But bestie, 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. Slay for portability 💅.

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. That's the whole locking strategy, no cap 🔥.

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. iykyk 🧚

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.
🚨 Runtime-check note: 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 🌈

Cute sign-off 🎀: this was mt-libtt-intro in the special file manual section — that footer/manual tag is the whole source/version/date situation as given, with no separate extra line printed beyond it, so that's the official end-of-page vibe. Bye bestie, go be iconic with your safely multithreaded ToolTalk code! 💖✨

📦 where this page comes from