SYNOPSIS
|
DESCRIPTION
On all platforms with threads support, Agar can be compiled with support for multithreading. Agar API calls, unless otherwise documented, then become free-threaded (safe to use from different threads without need for application-level synchronization). |
CONVENTIONS
The Agar API documentation follows the convention that all functions are
free-threaded, unless mentioned otherwise.
Under some circumstances, application-level synchronization is required. The AG_Object(3) simplifies this task by providing a per-object lock (which is implicitely acquired in some contexts, such as event handler execution). For instance, the following code accesses a VFS in an unsafe manner:
The following code should be used instead:
|
THREADS INTERFACE
When compiled with threads support, Agar provides a portable, minimal interface to the operating system's native threads interface. These functions follow Agar's standard error-handling style (see AG_Intro(3)). |
MUTEXES
Mutexes (MUTual EXclusion devices) are commonly used to protect shared
data structure against concurrent modifications.
The AG_MutexInit() function initializes a mutex structure. AG_MutexInitRecursive() initializes a recursive mutex (a mutex with a reference count), which allows nested AG_MutexLock() calls. AG_MutexDestroy() frees all resources allocated for a mutex. AG_MutexLock() and AG_MutexUnlock() respectively acquire and release a mutex. AG_MutexTryLock() tries to acquire a mutex without blocking and immediately returns 0 on success. On failure, the function returns -1, but does not set any error message (so AG_GetError(3) should not be used). |
CONDITION VARIABLES
THREADS
AG_ThreadCreate() creates a new thread executing fn. The optional argument arg is passed to fn. The AG_ThreadCancel() routine requests that the specified thread be cancelled. If the given thread is invalid, a fatal error is raised. The AG_ThreadJoin() function suspends the execution of the current thread until th terminates. When it does, the value passed to AG_ThreadExit() is made available in exitVal. AG_ThreadExit() terminates the current thread. exitVal is an optional user pointer. AG_ThreadKill() sends a signal to the specified thread. AG_ThreadSelf() returns the identifier of the current (caller's) thread. AG_ThreadEqual() returns 1 if the identifiers a and b both refer to the same thread, or 0 if they differ. |
THREAD-SPECIFIC VARIABLES
AG_ThreadKeyCreate() initializes a key (i.e., a handle) to a thread-specific value. The handle itself is accessible to all threads. The thread-specific value (i.e., the value specified by AG_ThreadKeySet(), and which defaults to NULL) will persist only for the life of the thread. If an optional destructor is given, that function will be called (with the thread-specific value as its argument), when the thread exists. The AG_ThreadKeyDelete() function releases resources allocated for a key. AG_ThreadKeyGet() returns the thread-specific value associated with key. AG_ThreadKeySet() sets a thread-specific value with key. |
SEE ALSO
AG_Intro(3), AG_Object(3) |
HISTORY
The AG_Threads interface first appeared in Agar 1.0 |