Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
AG_THREADS(3)	       FreeBSD Library Functions Manual		 AG_THREADS(3)

NAME
     AG_Threads	-- agar	threads	support

SYNOPSIS
     #include <agar/core.h>

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:

	   AG_Object *myObject;
	   myObject = AG_ObjectFind(myRoot, "/Foo");
	   if (myObject	!= NULL) { ... }		   /* UNSAFE */

     The following code	should be used instead:

	   AG_Object *myObject;
	   AG_ObjectLock(myRoot);
	   myObject = AG_ObjectFind(myRoot, "/Foo");
	   if (myObject	!= NULL) { ... }
	   AG_ObjectUnlock(myRoot);

THREADS	INTERFACE
     When compiled with	threads	support, Agar provides a portable, minimal in-
     terface to	the operating system's native threads interface.  These	func-
     tions 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.

     void AG_MutexInit(AG_Mutex	*mutex)

     int AG_MutexTryInit(AG_Mutex *mutex)

     void AG_MutexInitRecursive(AG_Mutex *mutex)

     int AG_MutexTryInitRecursive(AG_Mutex *mutex)

     void AG_MutexDestroy(AG_Mutex *mutex)

     void AG_MutexLock(AG_Mutex	*mutex)

     int AG_MutexTryLock(AG_Mutex *mutex)

     void AG_MutexUnlock(AG_Mutex *mutex)

     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 immedi-
     ately 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
     void AG_CondInit(AG_Cond *cv)

     int AG_CondTryInit(AG_Cond	*cv)

     void AG_CondDestroy(AG_Cond *cv)

     void AG_CondBroadcast(AG_Cond *cv)

     void AG_CondSignal(AG_Cond	*cv)

     int AG_CondWait(AG_Cond *cv, AG_Mutex *m)

     int AG_CondTimedWait(AG_Cond *cv, AG_Mutex	*m, const struct timespec *t)

     AG_CondInit() initializes a condition variable structure.

     AG_CondDestroy() releases resources allocated for a condition variable.

     AG_CondBroadcast()	unblock	all threads which are currently	blocked	wait-
     ing on cv.	 AG_CondSignal() unblocks at least one thread currently
     blocked waiting on	cv.

     AG_CondWait() blocks the calling thread until cv is signaled.  The
     AG_CondTimedWait()	variant	will not block for more	than the specified
     amount of time.

     All of these functions will raise a fatal condition if an error is	en-
     countered.

THREADS
     void AG_ThreadCreate(AG_Thread *th, void *(*fn)(void *arg), void *arg)

     int AG_ThreadTryCreate(AG_Thread *th, void	*(*fn)(void *arg), void	*arg)

     void AG_ThreadCancel(AG_Thread th)

     int AG_ThreadTryCancel(AG_Thread th)

     void AG_ThreadJoin(AG_Thread th, void **exitVal)

     int AG_ThreadTryJoin(AG_Thread th,	void **exitVal)

     void AG_ThreadExit(void *exitVal)

     void AG_ThreadKill(AG_Thread th, int signal)

     AG_Thread AG_ThreadSelf(void)

     int AG_ThreadEqual(AG_Thread a, AG_Thread b)

     AG_ThreadCreate() creates a new thread executing fn.  The optional	argu-
     ment arg is passed	to fn.

     The AG_ThreadCancel() routine requests that the specified thread be can-
     celled.  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
     void AG_ThreadKeyCreate(AG_ThreadKey *key,	void (*destructor)(void	*))

     int AG_ThreadKeyTryCreate(AG_ThreadKey *key, void (*destructor)(void *))

     void AG_ThreadKeyDelete(AG_ThreadKey key)

     int AG_ThreadKeyTryDelete(AG_ThreadKey key)

     void * AG_ThreadKeyGet(AG_ThreadKey key)

     void AG_ThreadKeySet(AG_ThreadKey key, const void *value)

     int AG_ThreadKeyTrySet(AG_ThreadKey key, const void *value)

     AG_ThreadKeyCreate() initializes a	key (i.e., a handle) to	a thread-spe-
     cific 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

FreeBSD	13.0		       November	16, 2007		  FreeBSD 13.0

NAME | SYNOPSIS | DESCRIPTION | CONVENTIONS | THREADS INTERFACE | MUTEXES | CONDITION VARIABLES | THREADS | THREAD-SPECIFIC VARIABLES | SEE ALSO | HISTORY

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=AG_Threads&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help