Thread C Library Functions
$Header: /cvsroot/aolserver/aolserver.com/docs/devel/c/index.html,v 1.1 2002/03/07 19:15:35 kriston Exp $
Wait for an event to be broadcast
Syntax
int Ns_AbsTimedWaitForEvent (
Ns_Cond* event,
Ns_Mutex* lock,
time_t abstime
);
Description
Wait for an event to be broadcast or the current time to be abstime,
whichever comes first.
Initialize a local thread storage variable.
Syntax
int Ns_AllocThreadLocalStorage(
Ns_ThreadLocalStorage * tls,
void (*destructor) (void *)
);
Description
Initializes a thread local storage variable and sets its destructor
function. The tls's value is initially NULL in all existing threads
and any new threads which are later created. If the destructor
function pointer is non-null and the tls is non-null in a particular
thread when it exits, the destructor will be called for that thread.
Thread local storage is often used to store data which must be shared
between unrelated functions much like global variables are used in a
single threaded program. Thread local storage is also often used to
provide buffer space unique to each thread when making older code
thread safe.
Examples
static Ns_ThreadLocalStorage tls;
void
Init(void)
{
/* This function is called once at startup. */
Ns_AllocThreadLocalStorage(&tls, Ns_Free);
}
char *
GetBuffer
{
void *ptr;
Ns_GetThreadLocalStorage(&tls, &ptr);
if (ptr == NULL) {
/* Allocate a buffer for this thread. */
ptr = Ns_Malloc(BUFFER_SIZE);
Ns_SetThreadLocalStorage(&tls, ptr);
}
return (char *) ptr;
}
Create a detached thread
Syntax
int Ns_BeginDetachedThread(
Ns_ThreadProc *start_routine,
void *arg
);
Description
Ns_BeginDetachedThread creates a thread which cleans up its data as
soon as it ends. Note that detached threads' ids can be reused
immediately by the system, and they cannot be waited on.
Examples
static void
ThreadStart(void *arg)
{
int n;
n = (int) arg;
Ns_Log(Notice, "%d: %d", Ns_GetThreadId(), n);
}
/*
* ManyThreads - Create 10 threads which all log a message.
*/
static void
ManyThreads(void)
{
int i;
for (i = 0; i < 10; ++i) {
Ns_BeginDetachedThread(ThreadStart, (void *) i);
}
}
Start a thread
Syntax
int Ns_BeginThread(
Ns_ThreadProc *start_routine,
void *arg,
Ns_Thread *thread
);
Description
Ns_BeginThread starts a new thread running start_routine and passwd
arg as its context. If thread is non-null it will be filled with the
thread's id. (see Ns_WaitForThread.)
Ns_ThreadCreate is the preferred function to start a thread.
Examples
static void
ThreadStart(void *arg)
{
int n;
n = (int) arg;
Ns_Log(Notice, "%d: %d", Ns_GetThreadId(), n);
}
/*
* ManyThreadWait - Create 10 threads which all log a message
* and wait for all of them to exit.
*/
static void
ManyThreadWait(void)
{
int i;
Ns_Thread tids[10];
for (i = 0; i < 10; ++i) {
Ns_BeginThread(ThreadStart, (void *) i, &tids[i]);
}
for (i = 0; i < 10; ++i) {
Ns_WaitForThread(&tids[i]);
}
}
Wake up events that are waiting to be triggered
Syntax
int Ns_BroadcastEvent(
Ns_Event * event
);
Description
Wake up all the threads waiting on the event. If no threads are
waiting on the event, this function has no effect.
Examples
static Ns_Event myev;
static Ns_Mutex mylock;
void
Init(void)
{
/* Initialize the lock and event at startup. */
Ns_InitializeMutex(&mylock);
Ns_InitializeEvent(&myev);
}
/* Lock the mutex and wait for the event. */
void
WaitFunc(void)
{
Ns_LockMutex(&mylock);
Ns_WaitForEvent(&myev, &mylock);
}
/* Wake up any waiting threads. */
void
BroadcastFunc(void)
{
Ns_BroadcastEvent(&myev);
}
Broadcast to condition variable
Syntax
void Ns_CacheBroadcast (
Ns_Cache* cache
);
Description
Broadcast to the cache's condition variable, waking all threads. Every
cache has an associated cond for user use. Every cache has an
associated cond for user use.
Create a new cache
Syntax
Ns_Cache* Ns_CacheCreate (
char* name,
int keys,
time_t timeout,
Ns_Callback* freeProc
);
Description
Create a new cache with the specified name. The keys argument is the
size of the cache key in system words. The timeout argument is the
time for cache entries to live. The freeProc argument is the
Ns_Callback to free cache entry data.
For a good example of how to use the Ns_Cache* functions, look at
nsd/fastpath.c.
Create a cache entry
Syntax
Ns_Entry* Ns_CacheCreateEntry (
Ns_Cache* cache,
char* key,
int* pnew
);
Description
Create a new cache entry in the specified cache. This function
emulates Tcl_CreateHashEntry's interface.
Create a size-based cache
Syntax
Ns_Cache* Ns_CacheCreateSz (
char* name,
int keys,
size_t maxsize,
Ns_Callback* freeProc
);
Description
Create a new size-based cache (a cache that has a maximum size in
bytes, specified by the maxsize argument). The keys argument is
TCL_STRING_KEYS or TCL_ONE_WORD_KEYS or an integer >=2, which is the
number of machine words needed to store a cache key. The freeProc
argument is the Ns_Callback to free cache entry data.
Delete a cache entry
Syntax
void Ns_CacheDeleteEntry (
Ns_Entry* entry
);
Description
Delete the specified entry from the cache table.
Find a cache
Syntax
Ns_Cache* Ns_CacheFind (
char* name
);
Description
Find a cache by name.
Find a cache entry
Syntax
Ns_Entry* Ns_CacheFindEntry (
Ns_Cache* cache,
char* key
);
Description
Find a cache entry.
Get first cache entry
Syntax
Ns_Entry* Ns_CacheFirstEntry (
Ns_Cache* cache,
Ns_CacheSearch* searchPtr
);
Description
Return a pointer to the first entry in the cache (Cache entries are
stored in no particular order.)
Flush all cache entries
Syntax
void Ns_CacheFlush (
Ns_Cache* cache
);
Description
Flush every entry from the specified cache.
Delete a cache entry
Syntax
void Ns_CacheFlushEntry (
Ns_Entry* entry
);
Description
Delete an entry from the cache table after first unsetting the current
entry value (if any).
Free allocated memory
Syntax
void Ns_CacheFree (
Ns_Cache* cache,
void* memPtr
);
Description
Frees memory allocated with Ns_CacheMalloc.
Get value of cache entry
Syntax
void* Ns_CacheGetValue (
Ns_Entry* entry
);
Description
Get the value (contents) of a cache entry.
Get key of cache entry
Syntax
char* Ns_CacheKey (
Ns_Entry* entry
);
Description
Gets the key of a cache entry.
Lock a cache
Syntax
void Ns_CacheLock (
Ns_Cache* cache
);
Description
Lock the cache. This must be done before performing any read/write
action on a cache.
Allocate memory
Syntax
void* Ns_CacheMalloc (
Ns_Cache* cache,
size_t len
);
Description
Allocate memory from a cache-local pool.
Get name of cache
Syntax
char* Ns_CacheName (
Ns_Entry* entry
);
Description
Get the name of the cache.
Get next cache entry
Syntax
Ns_Entry* Ns_CacheNextEntry (
Ns_CacheSearch* searchPtr
);
Description
Get the next cache entry. When used in conjunction with
Ns_CacheFirstEntry, you can traverse the whole cache.
Set value of cache entry
Syntax
void Ns_CacheSetValue (
Ns_Entry* entry,
void* value
);
Description
Set the value of a cache entry.
Set value of cache entry and adjust cache size
Syntax
void Ns_CacheSetValueSz (
Ns_Entry* entry,
void* value,
size_t size
);
Description
Free the cache entry's previous contents, set it to the new contents,
increase the size of the cache, and prune the cache until it's back
under the maximum size.
Signal cache's condition variable
Syntax
void Ns_CacheSignal (
Ns_Cache* cache
);
Description
Signal the cache's condition variable, waking the first waiting thread
(if any).
Note: Consider waking all threads with Ns_CacheBroadcast, instead.
Wait for cache entry to be set
Syntax
void* Ns_CacheTimedGetValue (
Ns_Cache* cache,
char* key,
Ns_Time* timePtr,
int* condPtr
);
Description
Wait for an entry's value to be set to non-null by some other thread
up to the given timeout or until an optional condition integer becomes
zero. Note that the cache and key are given instead of the entry
because you cannot rely on an entry to remain valid during the
Ns_CondTimedWait.
Wait for condition variable to be set
Syntax
int Ns_CacheTimedWait (
Ns_Cache* cache,
Ns_Time* timePtr
);
Description
Wait for the cache's condition variable to be signaled or the given
absolute timeout if timePtr is not NULL.
Unlock cache
Syntax
void Ns_CacheUnlock (
Ns_Cache* cache
);
Description
Unlock the specified cache.
Reset cache entry to null
Syntax
void Ns_CacheUnsetValue (
Ns_Entry* entry
);
Description
Reset the value of an entry to NULL, calling the free proc for any
previous entry and updating the cache size.
Wait indefinitely for condition variable to be set
Syntax
void Ns_CacheWait (
Ns_Cache* cache
);
Description
Wait indefinitely for the cache's condition variable to be signaled.
Wake up all threads waiting on a cond
Syntax
void Ns_CondBroadcast (
Ns_Cond*
);
Description
Wake up all threads that are waiting on a cond. For more informations
on condition variables, look at the pthread_cond_wait(3P) man page.
Free a cond's memory
Syntax
void Ns_CondDestroy (
Ns_Cond *condPtr
);
Description
Free a cond's memory.
Initialize a cond
Syntax
void Ns_CondInit (
Ns_Cond *condPtr
);
Description
Initialize a cond. You don't need to call this function if it is
initialized to 0, as is the case with static variables.
Wake up a single thread
Syntax
void Ns_CondSignal (
Ns_Cond *condPtr
);
Description
Wake up a single thread blocking on a cond.
Block on a cond
Syntax
int Ns_CondTimedWait (
Ns_Cond *condPtr ,
Ns_Mutex *mutexPtr ,
Ns_Time *timePtr
);
Description
Block on a cond until signaled or the specified time expires. The time
is absolute. The Ns_Time value can be manipulated with Ns_GetTime,
Ns_DiffTime, or Ns_IncrTime.
Wait indefinitely on a cond
Syntax
void Ns_CondWait (
Ns_Cond *condPtr ,
Ns_Mutex *mutexPtr
);
Description
Wait indefinetly on a cond.
Destroy a critical section object
Syntax
void Ns_CsDestroy(
Ns_Cs*
);
Description
Free the resources associated with the critical section.
Enter a critical section
Syntax
void Ns_CsEnter(
Ns_Cs *csPtr
);
Description
Enter the specified critical section. If the critical section is use
by another thread, the current will block until it is no longer so.
Note that critical sections are recursive and must be exited the same
number of times as they were entered.
Initialize a critical section
Syntax
void Ns_CsInit(
Ns_Cs *csPtr
);
Description
Initialize the specified critical section. It is recommended that you
use a mutex instead of a critical section if possible.
Leave a critical section
Syntax
void Ns_CsLeave(
Ns_Cs *csPtr
);
Description
Leave the specified critical section.
Free a critical section's resources
Syntax
int Ns_DestroyCriticalSection(
Ns_CriticalSection * section
);
Description
Free the resources associated with the critical section.
Ns_CsDestroy is the preferred function for freeing a critical
section's resources.
Free an event's resources
Syntax
int Ns_DestroyEvent(
Ns_Event * event
);
Description
Free the resources associated with the event object.
Free a mutual exclusion lock's resources
Syntax
int Ns_DestroyMutex(
Ns_Mutex * mutex
);
Description
Free the mutex's associated resources.
Ns_MutexDestroy is the preferred function for freeing a mutex's
resources.
Destroy a read/write lock
Syntax
int Ns_DestroyRWLock(
Ns_RWLock *lock
);
Description
Ns_DestroyRWLock frees the read/write lock's associated resources.
For general information about read/write locks and an example showing
the use of the read/write lock functions, see the Ns_InitializeRWLock
function.
Ns_RWLockDestroy is the preferred function for destroying a read/write
lock.
Free a semaphore's resources
Syntax
int Ns_DestroySemaphore(
Ns_Semaphore * sema
);
Description
Free the resources associated with the semaphore.
Ns_SemaDestroy is the preferred function for freeing a semaphore's
resources.
Enter a critical section
Syntax
int Ns_EnterCriticalSection(
Ns_CriticalSection * section
);
Description
Enter the specified critical section. If the critical section is use
by another thread, the current will block until it is no longer so.
Note that critical sections are recursive and must be exited the same
number of times as they were entered.
Ns_CsEnter is the preferred function for entering a critical section.
Free a thread or mark as exited
Syntax
void Ns_ExitThread (
int retcode
);
Description
Cleanup the thread's tls and memory pool and either free the thread if
it's detached or mark the thread as exited and allow it to be joined.
Ns_ThreadExit is the preferred function for freeing a thread.
Get the identifier for the current thread
Syntax
void Ns_GetThread(
Ns_Thread *thread
);
Description
Ns_GetThread fills in the unique thread identifier for the current
thread. (see Ns_WaitForThread)
Get the unique ID number for the current thread
Syntax
int Ns_GetThreadId(void);
Description
This routine tries to come up with a unique integer corresponding to
the current thread. (This is the integer that shows up in the log
files.) Often, this unique ID is the PID, but not always.
Get the thread local storage
Syntax
int Ns_GetThreadLocalStorage(
Ns_ThreadLocalStorage * tls,
void **p
);
Description
Fill *p with the value of the thread local storage. Note: If tls has
not been set within the current the thread *p will be set to NULL.
Ns_TlsGet is the preferred function for getting thread local storage.
Initialize a critical section
Syntax
int Ns_InitializeCriticalSection(
Ns_CriticalSection * section
);
Description
Initialize the specified critical section. It is recommended that you
use a mutex instead of a critical section if possible.
Ns_CsInit is the preferred function for initializing a critical
section.
Initialize an event object
Syntax
int Ns_InitializeEvent(
Ns_Event * event
);
Description
Initialize an event object.
Initialize a mutual exclusion lock
Syntax
int Ns_InitializeMutex(
Ns_Mutex * mutex
);
Description
Initialize a Mutual Exclusion lock for use.
Ns_MutexInit is the preferred function for initializing a mutex.
Initialize a read/write lock
Syntax
int Ns_InitializeRWLock(
Ns_RWLock *lock
);
Description
Initialize a read/write lock for use. A lock ID is returned via the
lock parameter, which can be used in the other read/write lock
functions.
About Read/Write Locks
Read/write locks are a serialization mechanism for using data
structures where multiple reads can happen simultaneously, but where
writes must happen singly. For example, suppose you have a hash table
that is heavily used but doesn't change very often. You'd like to have
multiple threads be able to read from the table without blocking on
each other, but when you need to update the table, you can do so
safely without having to worry about other threads reading incorrect
data.
The principal feature of read/write locks is the mechanism of which
locks have priority and which locks must wait. Any number of read
locks can be pending. If there's a write lock active, the read lock
acquisition blocks until the write lock is released. Also, only one
write lock can be in effect. If there are pending read locks active,
the write lock acquisition blocks until all of the read locks drain.
If a subsequent read lock acquisition attempt is made while a write
lock is waiting to acquire, the write lock has priority.
Ns_RWLockInit is the preferred function for initializing a read/write
lock.
Examples
NS_RWLock lock;
int GetData (int key)
{
/* acquire a read lock */
Ns_ReadLockRWLock (&lock);
search through the data structure looking for key's data;
/* release our read lock */
Ns_ReadUnlockRWLock (&lock);
return (value);
} /* GetData */
int StoreData (int key, int value)
{
/* acquire the write lock */
Ns_WriteLockRWLock (&lock);
manipulate the data structure storing key's value;
/* release the write lock */
Ns_WriteUnlockRWLock (&lock);
return (value);
} /* StoreData */
...
Ns_InitializeRWLock (&lock);
...
(different threads using GetData and StoreData)
...
Ns_DestoryRWLock (&lock);
Initialize a semaphore
Syntax
int Ns_InitializeSemaphore(
Ns_Semaphore * sema,
int beg_count
);
Description
Initialize the semaphore with a semaphore count of beg_count.
Ns_SemaInit is the preferred function for initializing a semaphore.
Leave a critical section
Syntax
int Ns_LeaveCriticalSection(
Ns_CriticalSection * section
);
Description
Leave the specified critical section.
Ns_CsLeave is the preferred function for leaving a critical section.
Create a mutual exclusion lock
Syntax
int Ns_LockMutex(
Ns_Mutex * mutex
);
Description
Acquire the mutex. If the mutex is already locked then the current
thread will block until the mutex is unlocked. Note: mutexes are not
recursive. If the current thread tries to lock the mutex twice in a
row, it will block or get an error depending on the platform.
Destroy a mutex object
Syntax
void Ns_MutexDestroy (
Ns_Mutex *mutexPtr
);
Description
Free the mutex's associated resources.
Initialize a mutex object
Syntax
void Ns_MutexInit (
Ns_Mutex *mutexPtr
);
Description
Initialize a Mutual Exclusion lock for use.
Lock a mutex object
Syntax
void Ns_MutexLock (
Ns_Mutex *mutexPtr
);
Description
Acquire the mutex. If the mutex is already locked then the current
thread will block until the mutex is unlocked. Note: mutexes are not
recursive. If the current thread tries to lock the mutex twice in a
row, it will block or get an error depending on the platform.
Unlock a mutex object
Syntax
void Ns_MutexUnlock (
Ns_Mutex *mutexPtr
);
Description
Unlock the mutex.
Acquire a read lock
Syntax
int Ns_ReadLockRWLock(
Ns_RWLock *lock
);
Description
Ns_ReadLockRWLock acquires a read lock. Any number of read locks can
be pending. If there's a write lock active, the read lock acquisition
blocks until the write lock is released.
For general information about read/write locks and an example showing
the use of the read/write lock functions, see the Ns_InitializeRWLock
function.
Ns_RWLockRdLock is the preferred function for acquiring a read lock.
Release a read lock
Syntax
int Ns_ReadUnlockRWLock(
Ns_RWLock *lock
);
Description
Ns_ReadUnlockRWLock releases a read lock.
For general information about read/write locks and an example showing
the use of the read/write lock functions, see the Ns_InitializeRWLock
function.
Ns_RWLockUnlock is the preferred function for releasing a lock.
Increment the semaphore count
Syntax
int Ns_ReleaseSemaphore(
Ns_Semaphore * sema,
int count
);
Description
Increment the semaphore count.
Ns_SemaPost is the preferred function for incrementing the semaphore
count.
Destroy a read/write lock
Syntax
void Ns_RWLockDestroy (
Ns_RWLock*
);
Description
Ns_RWLockDestroy frees the read/write lock's associated resources.
Initialize a read/write lock
Syntax
void Ns_RWLockInit (
Ns_RWLock*
);
Description
Initialize a read/write lock for use. A lock ID is returned via the
lock parameter, which can be used in the other read/write lock
functions.
About Read/Write Locks
Read/write locks are a serialization mechanism for using data
structures where multiple reads can happen simultaneously, but where
writes must happen singly. For example, suppose you have a hash table
that is heavily used but doesn't change very often. You'd like to have
multiple threads be able to read from the table without blocking on
each other, but when you need to update the table, you can do so
safely without having to worry about other threads reading incorrect
data.
The principal feature of read/write locks is the mechanism of which
locks have priority and which locks must wait. Any number of read
locks can be pending. If there's a write lock active, the read lock
acquisition blocks until the write lock is released. Also, only one
write lock can be in effect. If there are pending read locks active,
the write lock acquisition blocks until all of the read locks drain.
If a subsequent read lock acquisition attempt is made while a write
lock is waiting to acquire, the write lock has priority.
Acquire a read lock
Syntax
void Ns_RWLockRdLock (
Ns_RWLock *lockPtr
);
Description
Ns_RWLockRdLock acquires a read lock. Any number of read locks can be
pending. If there's a write lock active, the read lock acquisition
blocks until the write lock is released.
Release a read/write lock
Syntax
void Ns_RWLockUnlock (
Ns_RWLock *lockPtr
);
Description
Ns_RWLockUnlock releases a read or write lock.
Acquire a write lock
Syntax
void Ns_RWLockWrLock (
Ns_RWLock *lockPtr
);
Description
Ns_RWLockWrLock acquires a write lock. Only one write lock can be in
effect. If there are pending read locks active, the write lock
acquisition blocks until all of the read locks drain. If a subsequent
read lock acquisition attempt is made, the write lock has priority.
Destroy a semaphore object
Syntax
int Ns_SemaDestroy(
Ns_Sema*
);
Description
Free the resources associated with the semaphore.
Initialize a semaphore
Syntax
int Ns_SemaInit(
Ns_Sema* ,
int count
);
Description
Initialize the semaphore with a semaphore count of count.
Increment the semaphore count
Syntax
int Ns_SemaPost(
Ns_Sema* ,
int count
);
Description
Increment the semaphore count.
Wait for a semaphore count to be greater than zero.
Syntax
int Ns_SemaWait(
Ns_Sema*
);
Description
If the semaphore count is greater than zero, decrement it and
continue. Otherwise, block until this is possible.
Set thread local storage
Syntax
int Ns_SetThreadLocalStorage(
Ns_ThreadLocalStorage * tls,
void *p
);
Description
Set the thread local storage tls to the value p.
Examples
See the example for Ns_AllocThreadLocalStorage.
Ns_TlsSet is the preferred function for setting thread local storage.
Create new thread
Syntax
void Ns_ThreadCreate (
Ns_ThreadProc* proc,
void* arg,
long stackSize,
Ns_Thread* threadPtr
);
Description
Create a new thread.
Free or exit thread
Syntax
void Ns_ThreadExit (
int exitCode
);
Description
Cleanup the thread's tls and memory pool and either free the thread if
it's detached or mark the thread as exited and allow it to be joined.
Free thread pool memory
Syntax
void Ns_ThreadFree (
void* ptr
);
Description
Free previously allocated memory from the per-thread pool.
Get thread name
Syntax
char* Ns_ThreadGetName (void);
Description
Return a pointer to calling thread's string name, as set with
Ns_ThreadSetName.
Get thread ID
Syntax
int Ns_ThreadId (void);
Description
Return the numeric thread id for the calling thread.
Wait for thread exit
Syntax
void Ns_ThreadJoin (
Ns_Thread* threadPtr,
int* exitCodePtr
);
Description
Wait for exit of a non-detached thread.
Allocate thread pool memory
Syntax
void* Ns_ThreadMalloc (
unsigned int size
);
Description
Allocate thread-pool memory.
Get thread pool memory
Syntax
Ns_Pool* Ns_ThreadPool (void);
Description
Get this thread's memory pool.
Realloc thread pool memory
Syntax
void* Ns_ThreadRealloc (
void* ptr,
unsigned int size
);
Description
realloc for thread memory pools.
Get handle to thread
Syntax
void Ns_ThreadSelf (
Ns_Thread* threadPtr
);
Description
Return opaque handle to thread's data structure.
Set thread name
Syntax
void Ns_ThreadSetName (
char* name
);
Description
Set the name of the thread, which is used in the server.log. The name
can be retrieved with Ns_ThreadGetName.
Yield processor time to runnable threads
Syntax
void Ns_ThreadYield(void);
Description
Ns_ThreadYield yields its processor time to any runnable threads with
equal or higher priority.
Wait for an event for a specified time
Syntax
int Ns_TimedWaitForEvent(
Ns_Event * event,
Ns_Mutex * lock,
int usec
);
Description
Same as Ns_WaitForEvent except that it has a timeout in seconds. On
timeout, the function returns NS_TIMEOUT.
Examples
Ns_LockMutex(&lock);
if (!ready) {
result = Ns_TimedWaitForEvent(&ev, &lock, 10);
if (result == NS_TIMEOUT) {
... handle timeout ...
} else if (result != NS_OK) {
... handle error ...
}
}
Ns_UnlockMutex(&lock);
Allocate thread local storage
Syntax
void Ns_TlsAlloc (
Ns_Tls* ,
Ns_TlsCleanup*
);
Description
Allocate thread-local-storage. This is unneeded if the tls variable is
initialized to 0 (as static data is). See pthread_setspecific(3P) for
details on thread-local storage.
This function is a renamed version of Ns_AllocThreadLocalStorage.
Get thread local storage
Syntax
void* Ns_TlsGet (
Ns_Tls *tlsPtr
);
Description
Get thread-local-storage. This function is a renamed version of
Ns_GetThreadLocalStorage.
Set thread local storage
Syntax
void Ns_TlsSet (
Ns_Tls *tlsPtr ,
void *value
);
Description
Set thread local storage. This function is a renamed version of
Ns_SetThreadLocalStorage.
Unlock the mutual exclusion lock
Syntax
int Ns_UnlockMutex(
Ns_Mutex * mutex
);
Description
Unlock the mutex.
Ns_MutexLock is the preferred function for unlocking a mutex.
Examples
See the example for Ns_LockMutex.
Wait for an event for a specified time, in microseconds
Syntax
int Ns_UTimedWaitForEvent(
Ns_Event *event,
Ns_Mutex *lock,
int seconds,
int microseconds
);
Description
Same as Ns_WaitForEvent except that it has a timeout in microseconds.
On timeout, the function returns NS_TIMEOUT.
On the Irix platform, the timeout granularity is still in seconds. In
this case, if you specify a timeout of less than one second, it will
be treated as one second.
Wait for an event
Syntax
int Ns_WaitForEvent(
Ns_Event * event,
Ns_Mutex * lock
);
Description
Unlock the lock and wait for the event. This function blocks the
current thread's execution until the event has been set and it can
reacquire the lock. The mutex lock is locked before and after the
call.
Examples
static int ready = 0;
static Ns_Event ev;
static Ns_Mutex lock;
void
Init(void)
{
Ns_InitializeMutex(&lock);
Ns_InitializeEvent(&ev);
}
void
Waiter(void)
{
Ns_LockMutex(&lock);
if (!ready) {
Ns_WaitForEvent(&ev, &lock);
}
Ns_UnlockMutex(&lock);
... resource ready ...
}
Wait for a semaphore count to be greater than zero.
Syntax
int Ns_WaitForSemaphore(
Ns_Semaphore * sema
);
Description
If the semaphore count is greater than zero, decrement it and
continue. Otherwise, block until this is possible.
Ns_SemaWait is the preferred function for waiting for a semaphore.
Examples
static Ns_Semaphore sem;
void
Init(void)
{
Ns_InitializeSemaphore(&sem, 0);
}
void
Waiter(void)
{
Ns_WaitForSemaphore(&sem);
... access resource ...
}
void
Releaser(void)
{
Ns_ReleaseSemaphore(&sem, 1);
}
Wait for a thread to exit
Syntax
int Ns_WaitForThread(
Ns_Thread *thread
);
Description
This routine blocks the current thread's execution until the specified
thread exits.
Examples
See the example for Ns_BeginThread.
Wait for thread to exit
Syntax
int Ns_WaitThread (
Ns_Thread* thread,
int* retcode
);
Description
This function blocks the current thread's execution until the
specified thread exits.
Acquire a write lock
Syntax
int Ns_WriteLockRWLock(
Ns_RWLock *lock
);
Description
Ns_WriteLockRWLock acquires a write lock. Only one write lock can be
in effect. If there are pending read locks active, the write lock
acquisition blocks until all of the read locks drain. If a subsequent
read lock acquisition attempt is made, the write lock has priority.
For general information about read/write locks and an example showing
the use of the read/write lock functions, see the Ns_InitializeRWLock
function.
Ns_RWLockWrLock is the preferred function for acquiring a write lock.
Release a write lock.
Syntax
int Ns_WriteUnlockRWLock(
Ns_RWLock *lock
);
Description
Ns_WriteUnlockRWLock releases a write lock.
For general information about read/write locks and an example showing
the use of the read/write lock functions, see the Ns_InitializeRWLock
function.
Ns_RWLockUnlock is the preferred function for releasing a lock.