semaphore(3synch)                                  semaphore(3synch)


       NAME
             semaphore: sema_destroy, sema_init, sema_post, sema_trywait,
             sema_wait - overview of semaphore routines

       SYNOPSIS
             cc [options] -Kthread file
             #include <synch.h>
             int sema_init(sema_t *sema, int sema_count, int type, void *arg);
             int sema_wait(sema_t *sema);
             int sema_trywait(sema_t *sema);
             int sema_post(sema_t *sema);
             int sema_destroy(sema_t *sema);

          Parameters
             sema        pointer to semaphore to initialize, post, wait
                         for, or destroy

             sema_count  number of resources to be protected by the
                         semaphore

             type        USYNC_THREAD or USYNC_PROCESS

             arg         NULL (reserved for future use)

       DESCRIPTION
             Conceptually, a semaphore is a count of free resources.
             Semaphores are typically used to coordinate access to
             resources.  The semaphore count is initialized with sema_init
             to the number of free resources.  Threads then atomically
             increment the count with sema_post when resources are added
             and atomically decrement the count with sema_wait when
             resources are removed.  When the semaphore count becomes zero,
             indicating that no more resources are present, threads trying
             to decrement the semaphore with sema_wait will block until a
             resource becomes available.

             If there is only one resource to protect (that is, the
             semaphore count will never be greater than one), a mutex lock
             will provide better performance than a semaphore.

             Note that semaphores protect data only when the convention of
             calling sema_wait and sema_post is faithfully followed before
             and after any access of the data.





                           Copyright 1994 Novell, Inc.               Page 1

      semaphore(3synch)                                  semaphore(3synch)


         sema_init
            sema_init initializes the semaphore sema of type type to
            protect sema_count resources.

         sema_wait
            sema_wait acquires the semaphore pointed to by sema.

            If the semaphore is available (that is, if the semaphore value
            is greater than zero), sema_wait decrements the semaphore
            value and returns to the caller.

            If the semaphore is unavailable (that is, the semaphore value
            is zero or less), sema_wait decrements the semaphore value and
            suspends execution of the calling thread until the semaphore
            becomes available to the caller.

            If a thread waiting on a semaphore is interrupted by a signal,
            the signal handler will run, but then the thread will resume
            waiting for the semaphore.  Thus, when sema_wait returns
            without an error, it will always have acquired the semaphore.

         sema_trywait
            sema_trywait makes a single attempt to acquire the semaphore
            pointed to by sema.  If the semaphore is available,
            sema_trywait decrements the semaphore value and returns to the
            caller.

            If sema_trywait cannot immediately acquire the semaphore, it
            returns EBUSY to the caller, it does not block the caller to
            wait for the semaphore or decrement the semaphore value.

         sema_post
            sema_post increments the count of the semaphore pointed to by
            sema, and if the new count value is less than or equal to
            zero, makes the next thread waiting at the semaphore runnable.

            If more than one thread is waiting, release from the blocked
            group is scheduling policy-specific for bound threads, and may
            be dependent on scheduling parameters for multiplexed threads.

         sema_destroy
            sema_destroy destroys the semaphore pointed to by sema.  This
            includes invalidating sema and freeing any associated
            dynamically allocated resources.




                          Copyright 1994 Novell, Inc.               Page 2

       semaphore(3synch)                                  semaphore(3synch)


       USAGE
          Warnings
             Operations on semaphores initialized with sema_init are not
             recursive; a thread can block itself if it attempts to
             reacquire a semaphore that it has already acquired.

       REFERENCES
             sema_destroy(3synch) sema_init(3synch) sema_post(3synch),
             sema_trywait(3synch), sema_wait(3synch), synch(3synch)







































                           Copyright 1994 Novell, Inc.               Page 3