SCO OpenServer

wakeup(D3oddi)

wakeup, wakeupn -- wake up a sleeping process

Synopsis

void wakeup(caddr_t address);
unsigned int wakeupn(caddr_t address, int maxwake);

Description

The wakeup( ) function causes all processes that are sleeping at the specified address to be taken off the sleep queue. If the process is running, the unblocked processes are placed on the run queue. If the process is stopped, the unblocked process is taken off the sleep queue (but not placed it on the run queue). When a process is awakened, the call to sleep(D3oddi) returns a value of zero. It is still necessary to see whether the event being slept on has occurred, because there is no guarantee that the resource being waited for is actually free.

The wakeupn( ) function behaves the same way as wakeup( ), except that it only wakes up a maximum of maxwake processes.

Arguments

address: Address that was passed to the corresponding call to sleep(D3) which caused the process to be suspended. This number is not guaranteed to be unique and multiple processes may have have been awakened by any single invocation of the wakeup( ) function, so it is not guaranteed that the event being waited for has in fact occurred.
maxwake: Maximum number of processes to be awakened.

Return values

wakeup( ) does not return a value. wakeupn( ) returns the number of processes placed on the run queue.

Usage

Use wakeupn( ) when several processes await the availability of a small number of resources. Using wakeupn( ) avoids the system overhead of awakening all sleeping processes only to have them put back to sleep because the resource has been allocated to one of the other unblocked processes.

Context and synchronization

Non-blockable, interrupt, user, or blockable context.

Hardware applicability

All

Version applicability

wakeup: oddi: 1, 2, 2mp, 3, 3mp, 4, 4mp, 5, 5mp, 6, 6mp
wakeupn: oddi: 3, 3mp, 4, 4mp, 5, 5mp

SVR5 DDI compatibility

DDI version 6 and earlier supports the wakeup(D3) function with identical syntax and behavior to the ODDI function. These earlier versions of DDI do not support functionality similar to wakeupn( ).

DDI versions 7 and earlier use synchronization variables rather than sleep( ) and wakeup( ). In this scheme, SV_BROADCAST(D3) is roughly equivalent to wakeup( ) and SV_SIGNAL(D3) unblocks a single LWP, which is equivalent to the way wakeupn( ) is typically used. See ``Synchronization variables'' in HDK Technical Reference for more information about DDI sychronization variables and a comparison of their semantics with sleep( ) and wakeup( ).

References

delay(D3oddi), sleep(D3oddi), timeout(D3oddi)

Examples

The following code fragments demonstrate one possible use of sleep( ) and wakeup( ). In this instance the driver's read(D2oddi) routine allocates a temporary storage area, queues an I/O transfer, and then puts the process to sleep. After the transfer is complete, the intr(D2oddi) routine executes a wakeup( ). Note that this example does not address the possibility that multiple user processes may have queued requests for a single device.

   char my_address;             /* declare variable which is used for address */
   
   xxread(int dev); {
   #define MYPRI	PZERO+15  /* PZERO is defined in <sys/param.h> */
   

           /* allocate temporary storage */
           /* set flag to indicate I/O transfer is in progress */
           /* start I/O transfer */
           /*
            * flag only indicates transfer is done if wakeup() has
            * been called by my xxintr().
            */
           while (/* flag indicates transfer is not done */) {
         		/*
   		 * OR MYPRI with PCATCH to clean things up instead
          		 * of returning directly to user space with an error.
   	         */
   		if (sleep(&my_address, MYPRI | PCATCH) == 1) {
   	                /* stop I/O transfer       */
   	                /* clear I/O transfer flag */
   	                /* free temporary memory   */
   	                u.u_error = EINTR;
   	                return(-1);
   	                }
          		} /* only get past here when transfer is done */
           /* copy data from temporary storage to user address */
           .
           /* free temporary memory */
           return( /* number of bytes transferred */ );
   }
   

   xxintr(int interrupt); {
           /* ``check that transfer is'' complete */
           /* ``set flag to indicate transfer is complete'' */
           /* wakeup sleeping process */
           wakeup(&my_address);
   }