SEM.DOC

			      sem.library

	      (c)Copyright 1991, Matthew Dillon, All Rights Reserved

		       SIMPLE TASK SEMAPHORE LIBRARY

sem.library/CreateSem
sem.library/DeleteSem
sem.library/ExclSem
sem.library/SharSem
sem.library/WaitSem
sem.library/SigsSem
sem.library/RelsSem
sem.library/sem_notes

sem.library/CreateSem				    sem.library/CreateSem

    NAME
	CreateSem - Create a semaphore

    SYNOPSIS
	sem  = CreateSem(name)
	D0		 D0

	void *sem;	/*  returned semaphore or NULL		*/
	char *name;	/*  name of semaphore to create 	*/

    FUNCTION
	CreateSem() creates a semaphore with the specified name.  The
	semaphore is completely independant of the task.  Another task
	creating the same semaphore name will return the same semaphore.
	It is legal for a task to exit without deleting the semaphore it
	created, but not legal for a task to exit while holding an exclusive
	lock on the semaphore.

	<name> is case sensitive.  NULL is returned if memory could not be
	allocated.  SIGF_SINGLE will be used for signalling (i.e. no signal
	bits are allocated).

sem.library/DeleteSem				    sem.library/DeleteSem

    NAME
	DeleteSem - Delete a semaphore

    SYNOPSIS
	void   DeleteSem(sem)
			 D0

	void *sem;	/*  semaphore to delete 	    */

    FUNCTION
	DeleteSem() deletes a previously created semaphore.  DeleteSem()
	does not release any locks you may have on the semaphore.

	If this is the last reference to the semaphore and no locks are
	held on it, the semaphore will be freed from memory.  Note that
	in order to expunge the library all semaphores must be freed, it
	is not enough to bring the lib open-count to 0.


sem.library/ExclSem				    sem.library/ExclSem

    NAME
	ExclSem - obtain an exclusive lock on a semaphore

    SYNOPSIS
	void   ExclSem(sem)
			D0

	void *sem;	/*  semaphore to delete 	    */

    FUNCTION
	ExclSem() obtains an exclusive lock on the specified semaphore
	and will block until the lock can be obtained.

	It is legal to obtain an exclusive lock on a semaphore you already
	have an exclusive lock on.  It is NOT legal to upgrade a shared
	lock into an exclusive lock with this call.

sem.library/SharSem				    sem.library/SharSem

    NAME
	SharSem - obtain a shared lock on a semaphore

    SYNOPSIS
	void   SharSem(sem)
			D0

	void *sem;	/*  semaphore to delete 	    */

    FUNCTION
	SharSem() obtains a shared lock on the specified semaphore and will
	block until the lock can be obtained.  Several tasks may hold
	shared locks on a semaphore at a time, but only one can hold an
	exclusive lock.

	It is not legal to downgrade an exclusive lock held by your task to
	a shared lock with this call.

sem.library/WaitSem				    sem.library/WaitSem

    NAME
	WaitSem - release current lock, wait for signal, regain current lock

    SYNOPSIS
	void   WaitSem(sem)
			D0

	void *sem;	/*  semaphore to delete 	    */

    FUNCTION
	WaitSem() requires that you have already obtained either a shared
	or exclusive lock on the semaphore with SharSem() or ExclSem().

	WaitSem() will atomically release the lock and wait for the
	semaphore to be signalled with SigsSem().  Once signalled, the
	original lock will be regained.  Note that regaining the lock
	will also block until the lock is available.

	If you previously held an exclusive lock then when this call
	returns you will still hold an exclusive lock.	If you previously
	held a shared lock then when this call returns you will still hold
	a shared lock.

	WARNING, It is illegal to use WaitSem() on a semaphore which has
	been exclusively locked by the same task multiple times.

sem.library/SigsSem				    sem.library/SigsSem

    NAME
	SigsSem - signal first task waiting on a semaphore with WaitSem()

    SYNOPSIS
	void   SigsSem(sem, n)
			D0, D1

	void *sem;	/*  semaphore to delete 	    */
	long n; 	/*  # of tasks to wake up	    */

    FUNCTION
	SigsSem() signals the first N tasks waiting on a semaphore with
	WaitSem().  Note that even after woken up these tasks may block
	trying to regain the lock they held.

	Specify n = -1 to wake up all tasks, n = 1 to wake up only 1, or
	some other number to wake up a specific number of tasks.

    USES
	WaitSem()/SigsSem() are useful for, say, allocating and freeing
	buffers from a cache of limited size.  The allocate / free calls
	would use an exclusive lock to prevent simultanious access to the
	cache, and further the allocator would use WaitSem() when no
	buffers are available, and the free routine would use SigsSem()
	when it has regained a buffer, thus providing an efficient
	mechanism for both locking and action-signalling.


sem.library/RelsSem				    sem.library/RelsSem

    NAME
	RelsSem -  release a semaphore that you have previously obtained

    SYNOPSIS
	void   RelsSem(sem)
			D0

	void *sem;	/*  semaphore to delete 	    */

    FUNCTION
	RelsSem() releases a previously obtained semaphore.  It is legal to
	release a semaphore obtained by another task though obviously you
	only want to do so if you have designed it into your system.

	Releasing a semaphore may wake up other tasks waiting for it, but
	will NOT wake up tasks blocked in a WaitSem() unless they have
	first been woken up with SigsSem().

sem.library/sem_notes				    sem.library/sem_notes

    This semaphore library was created for everyone's use.  Any comments
    and suggestions are welcome.  Future plans include a demotion
    (excl->shar) and promotion (shar->excl) call, as well as non-blocking
    calls.

    I can be reached at:

	UUCP:	dillon@overload.Berkeley.CA.US

	BIX:	mdillon

	USMAIL: Matthew Dillon
		891 Regal Rd.
		Berkeley, Ca. 94708
		USA