Ns_Master(3aolserver) AOLserver Library Procedures Ns_Master(3aolserver)__________________________________________________________________________________________________________________________________________________NAME
Ns_MasterLock, Ns_MasterUnlock - Enter and leave the single master critical section lock
SYNOPSIS
#include "ns.h"
void
Ns_MasterLock(void)
void
Ns_MasterUnlock(void)
_________________________________________________________________DESCRIPTION
The single master critical section lock is used throughout the core server to protect portions of code from being run by more than one
thread at a time. These are convenience functions which actually make calls to Ns_CsEnter and Ns_CsLeave to perform the locking and unlock-
ing function.
You should not use these functions in your modules. To protect critical sections in your modules you should create and initialize your own
named locks, then wrap your critical sections with calls to Ns_CsEnter and Ns_CsLeave.
Ns_MasterLock()
Enter the single master lock. The thread that holds this lock is guaranteed exclusive access to the section of code that follows the
call to Ns_MasterLock. Other threads that attempt to enter the master critical section while another thread owns the master lock
will block until the owning thread releases the master lock.
Be extremely careful with code you place within the master critical section. If the thread that owns the master lock blocks for any
reason while in the master critical section, other threads that need to enter that section of code will block until the master lock
is released.
Ns_MasterUnlock()
Leave the single master critical section. The thread that owns the lock must release it after the critical section of code has com-
pleted so that other threads may execute the critical section code.
SEE ALSO nsd(1), info(n), Ns_CsEnter(3), Ns_CsLeave(3)KEYWORDS AOLserver 4.0 Ns_Master(3aolserver)
Check Out this Related Man Page
Ns_CritSec(3aolserver) AOLserver Library Procedures Ns_CritSec(3aolserver)__________________________________________________________________________________________________________________________________________________NAME
, Ns_CsDestroy, Ns_CsEnter, Ns_CsInit, Ns_CsLeave - Manage and use critical section locks
SYNOPSIS
#include "ns.h"
void
Ns_CsDestroy(Ns_Cs *csPtr)
void
Ns_CsEnter(Ns_Cs *csPtr)
void
Ns_CsInit(Ns_Cs *csPtr)
void
Ns_CsLeave(Ns_Cs *csPtr)
_________________________________________________________________DESCRIPTION
Critical section locks are used to prevent more than one thread from executing a specific section of code at one time. They are implemented
as "objects", which simply means that memory is allocated to hold the lock state. They can also be called "sychronization objects".
While a thread is executing a critical section of code, all other threads that want to execute that same section of code must wait until
the lock surrounding that critical section has been released.
This is crucial to prevent race conditions which could put the server into an unknown state. For example, if a section of code frees a
pointer and then decrements a counter that stores how many pointers exist, it is possible that the counter value and the actual number of
pointers may be different. If another section of the server relies on this counter and reads it when the pointer has been freed, but the
counter has not yet been decremented, it could crash the server or put it into an unknown state.
Critical section locks should be used sparingly as they will adversely impact the performance of the server or module. They essentially
cause the section of code they enclose into behaving in a single-threaded manner. If a critical section executes slowly or blocks, other
threads that must execute that section of code will begin to block as well until the critical section lock is released.
You will normally want to wrap sections of code that are used to both read and write values, create and destroy pointers and structures or
otherwise look at or modify data in the system. Use the same named lock for both read and write operations on the same data.
Threads that are waiting for a critical section lock to be released do not have to poll the lock. The critical section lock functions use
thread condition functions to signal when a lock is released.
Ns_CsDestroy(csPtr)
Destroy a critical section object. Note that you would almost never need to call this function as synchronization objects are typi-
cally created at startup and exist until the server exits.
The underlying objects in the critical section are destroyed and the critical section memory returned to the heap.
Ns_CsEnter(csPtr)
Lock a critical section object, initializing it first if needed. If the critical section is in use by another thread, the calling
thread 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_CsInit(csPtr)
Initialize a critical section object. Memory will be allocated to hold the object's state.
Ns_CsLeave(csPtr)
Unlock a critical section once. A count of threads waiting to enter the critical section is kept, and a condition is signaled if
this is the final unlock of the critical section so that other threads may enter the critical section.
SEE ALSO nsd(1), info(n), Ns_MasterLock(3), Ns_MasterUnlock(3), Ns_CondDestroy(3), Ns_CondSignal(3), Ns_CondWait(3), Ns_MutexLock(3), Ns_MutexUn-
lock(3)KEYWORDS AOLserver 4.0 Ns_CritSec(3aolserver)