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 typically 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_MutexUnlock(3)

KEYWORDS