ScheduleWorkToDo

Schedules a routine as work, which puts it on the highest priority queue, the WorkToDoList

Local Servers:blocking
Remote Servers:N/A
Classification:4.x, 5.x, 6.x
Service:Thread

Syntax

  #include <nwthread.h>  
   
  int ScheduleWorkToDo  (  
     void       (*ProcedureToCall) ( ) ,  
     void       *workData,   
     WorkToDo   *workToDo);

Parameters

ProcedureToCall
(IN) Points to the routine being scheduled as work.
workData
(IN) Points to the data to be passed to the worker thread.
workToDo
(IN) Points to a WorkToDo structure.

Return Values

The following table lists return values and descriptions.

0

Success

5

ENOMEM

Remarks

This function schedules work to be executed by an OS worker thread.

The ProcedureToCall parameter points to the procedure to be scheduled as work. Work is a high-priority, low overhead procedure. See When to Schedule a Routine as Work.

The workData parameter contains the data to be passed to ProcedureToCall.

The workToDo parameter is a structure used by CLIB.NLM to set up WorkToDo process scheduling. The structure must be allocated before calling this function and released afterward (for example, by calling malloc and free). Other than allocating workToDo, the developer does not need to be concerned with the details of this stucture since the only user-defined fields in the structure are set by the ProcedureToCall and workData parameters. WorkToDo is defined in nwthread.h.

Since the work that is scheduled is done by an OS worker thread, it is not be able to use the NetWare API functions that use context, unless context is given to the OS worker thread.

The context that is given to the OS worker thread is determined by the value in the registering thread’s context specifier. You can set the context specifier to one of the following options:

  • NO_CONTEXT-Callbacks registered with this option are not given CLIB context. The advantage here is that you avoid the overhead needed for setting up CLIB context. The disadvantage is that without the context the callback is only able to call NetWare API functions that manipulate data or manage local semaphores.

    Once inside of your callback, you can manually give your callback thread CLIB context by calling SetThreadGroupID and passing in a valid thread group ID. If you manually set up your context, you need to reset its context to its original context, by setting the thread group ID back to its original value.

  • USE_CURRENT_CONTEXT-Callbacks registered with a thread that has its context specifier set to USE_CURRENT_CONTEXT have the thread group context of the registering thread.
  • A valid thread group ID-This is to be used when you want the callbacks to have a different thread group context than the thread that schedules them.

When a new thread is started with BeginThread, BeginThreadGroup or ScheduleWorkToDo, its context specifier is set to USE_CURRENT_CONTEXT by default.

You can determine the current setting of the registering thread’s context specifier by calling GetThreadContextSpecifier. You use SetThreadContextSpecifier to set the registering thread’s context specifier to one of the above options.

For more information on using CLIB context, see Context Problems with OS Threads.

See Also

BeginThread, BeginThreadGroup

Example

  #include <stdio.h>  
  #include <nwthread.h>  
  #include <nwconio.h>  
   
  int   count = 0;  
   
  /*........................*/  
  void ScreenUpdater(void *data)  
  {  
     data = data;  
     count++;  
     clrscr();  
     printf("You could use a work to do thread\n\n");  
     printf("to do screen updates.  %i.\n\n\n", count);  
     printf("Work to do threads get into the\n\n");  
     printf("system fast and are useful to\n\n");  
     printf("accomplish finite definable tasks.");  
  }  
   
  /*........................*/  
  main()  
  {  
     WorkToDo   screenWork;  
     char       ch = 0;  
     SetAutoScreenDestructionMode(TRUE);  
     while (ch != ’q’)  
     {  
        ScheduleWorkToDo(ScreenUpdater, NULL, &screenWork);  
   
        /* ThreadSwitch makes sure work to do gets a chance to run. */  
        ThreadSwitch();  
        if (!kbhit())  
        ThreadSwitchWithDelay();  
        else  
        ch = getch();  
     }  
  }  
  /*........................*/