home *** CD-ROM | disk | FTP | other *** search
/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 463.lha / SemLibrary / sem.doc < prev    next >
Text File  |  1991-01-04  |  6KB  |  199 lines
  1.  
  2.                 SEM.DOC
  3.  
  4.                   sem.library
  5.  
  6.           (c)Copyright 1991, Matthew Dillon, All Rights Reserved
  7.  
  8.                SIMPLE TASK SEMAPHORE LIBRARY
  9.  
  10. sem.library/CreateSem
  11. sem.library/DeleteSem
  12. sem.library/ExclSem
  13. sem.library/SharSem
  14. sem.library/WaitSem
  15. sem.library/SigsSem
  16. sem.library/RelsSem
  17. sem.library/sem_notes
  18.  
  19. sem.library/CreateSem                    sem.library/CreateSem
  20.  
  21.     NAME
  22.     CreateSem - Create a semaphore
  23.  
  24.     SYNOPSIS
  25.     sem  = CreateSem(name)
  26.     D0         D0
  27.  
  28.     void *sem;    /*  returned semaphore or NULL        */
  29.     char *name;    /*  name of semaphore to create     */
  30.  
  31.     FUNCTION
  32.     CreateSem() creates a semaphore with the specified name.  The
  33.     semaphore is completely independant of the task.  Another task
  34.     creating the same semaphore name will return the same semaphore.
  35.     It is legal for a task to exit without deleting the semaphore it
  36.     created, but not legal for a task to exit while holding an exclusive
  37.     lock on the semaphore.
  38.  
  39.     <name> is case sensitive.  NULL is returned if memory could not be
  40.     allocated.  SIGF_SINGLE will be used for signalling (i.e. no signal
  41.     bits are allocated).
  42.  
  43. sem.library/DeleteSem                    sem.library/DeleteSem
  44.  
  45.     NAME
  46.     DeleteSem - Delete a semaphore
  47.  
  48.     SYNOPSIS
  49.     void   DeleteSem(sem)
  50.              D0
  51.  
  52.     void *sem;    /*  semaphore to delete         */
  53.  
  54.     FUNCTION
  55.     DeleteSem() deletes a previously created semaphore.  DeleteSem()
  56.     does not release any locks you may have on the semaphore.
  57.  
  58.     If this is the last reference to the semaphore and no locks are
  59.     held on it, the semaphore will be freed from memory.  Note that
  60.     in order to expunge the library all semaphores must be freed, it
  61.     is not enough to bring the lib open-count to 0.
  62.  
  63.  
  64. sem.library/ExclSem                    sem.library/ExclSem
  65.  
  66.     NAME
  67.     ExclSem - obtain an exclusive lock on a semaphore
  68.  
  69.     SYNOPSIS
  70.     void   ExclSem(sem)
  71.             D0
  72.  
  73.     void *sem;    /*  semaphore to delete         */
  74.  
  75.     FUNCTION
  76.     ExclSem() obtains an exclusive lock on the specified semaphore
  77.     and will block until the lock can be obtained.
  78.  
  79.     It is legal to obtain an exclusive lock on a semaphore you already
  80.     have an exclusive lock on.  It is NOT legal to upgrade a shared
  81.     lock into an exclusive lock with this call.
  82.  
  83. sem.library/SharSem                    sem.library/SharSem
  84.  
  85.     NAME
  86.     SharSem - obtain a shared lock on a semaphore
  87.  
  88.     SYNOPSIS
  89.     void   SharSem(sem)
  90.             D0
  91.  
  92.     void *sem;    /*  semaphore to delete         */
  93.  
  94.     FUNCTION
  95.     SharSem() obtains a shared lock on the specified semaphore and will
  96.     block until the lock can be obtained.  Several tasks may hold
  97.     shared locks on a semaphore at a time, but only one can hold an
  98.     exclusive lock.
  99.  
  100.     It is not legal to downgrade an exclusive lock held by your task to
  101.     a shared lock with this call.
  102.  
  103. sem.library/WaitSem                    sem.library/WaitSem
  104.  
  105.     NAME
  106.     WaitSem - release current lock, wait for signal, regain current lock
  107.  
  108.     SYNOPSIS
  109.     void   WaitSem(sem)
  110.             D0
  111.  
  112.     void *sem;    /*  semaphore to delete         */
  113.  
  114.     FUNCTION
  115.     WaitSem() requires that you have already obtained either a shared
  116.     or exclusive lock on the semaphore with SharSem() or ExclSem().
  117.  
  118.     WaitSem() will atomically release the lock and wait for the
  119.     semaphore to be signalled with SigsSem().  Once signalled, the
  120.     original lock will be regained.  Note that regaining the lock
  121.     will also block until the lock is available.
  122.  
  123.     If you previously held an exclusive lock then when this call
  124.     returns you will still hold an exclusive lock.    If you previously
  125.     held a shared lock then when this call returns you will still hold
  126.     a shared lock.
  127.  
  128.     WARNING, It is illegal to use WaitSem() on a semaphore which has
  129.     been exclusively locked by the same task multiple times.
  130.  
  131. sem.library/SigsSem                    sem.library/SigsSem
  132.  
  133.     NAME
  134.     SigsSem - signal first task waiting on a semaphore with WaitSem()
  135.  
  136.     SYNOPSIS
  137.     void   SigsSem(sem, n)
  138.             D0, D1
  139.  
  140.     void *sem;    /*  semaphore to delete         */
  141.     long n;     /*  # of tasks to wake up        */
  142.  
  143.     FUNCTION
  144.     SigsSem() signals the first N tasks waiting on a semaphore with
  145.     WaitSem().  Note that even after woken up these tasks may block
  146.     trying to regain the lock they held.
  147.  
  148.     Specify n = -1 to wake up all tasks, n = 1 to wake up only 1, or
  149.     some other number to wake up a specific number of tasks.
  150.  
  151.     USES
  152.     WaitSem()/SigsSem() are useful for, say, allocating and freeing
  153.     buffers from a cache of limited size.  The allocate / free calls
  154.     would use an exclusive lock to prevent simultanious access to the
  155.     cache, and further the allocator would use WaitSem() when no
  156.     buffers are available, and the free routine would use SigsSem()
  157.     when it has regained a buffer, thus providing an efficient
  158.     mechanism for both locking and action-signalling.
  159.  
  160.  
  161. sem.library/RelsSem                    sem.library/RelsSem
  162.  
  163.     NAME
  164.     RelsSem -  release a semaphore that you have previously obtained
  165.  
  166.     SYNOPSIS
  167.     void   RelsSem(sem)
  168.             D0
  169.  
  170.     void *sem;    /*  semaphore to delete         */
  171.  
  172.     FUNCTION
  173.     RelsSem() releases a previously obtained semaphore.  It is legal to
  174.     release a semaphore obtained by another task though obviously you
  175.     only want to do so if you have designed it into your system.
  176.  
  177.     Releasing a semaphore may wake up other tasks waiting for it, but
  178.     will NOT wake up tasks blocked in a WaitSem() unless they have
  179.     first been woken up with SigsSem().
  180.  
  181. sem.library/sem_notes                    sem.library/sem_notes
  182.  
  183.     This semaphore library was created for everyone's use.  Any comments
  184.     and suggestions are welcome.  Future plans include a demotion
  185.     (excl->shar) and promotion (shar->excl) call, as well as non-blocking
  186.     calls.
  187.  
  188.     I can be reached at:
  189.  
  190.     UUCP:    dillon@overload.Berkeley.CA.US
  191.  
  192.     BIX:    mdillon
  193.  
  194.     USMAIL: Matthew Dillon
  195.         891 Regal Rd.
  196.         Berkeley, Ca. 94708
  197.         USA
  198.  
  199.