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