home *** CD-ROM | disk | FTP | other *** search
/ Tools / WinSN5.0Ver.iso / NETSCAP.50 / WIN1998.ZIP / ns / modules / schedulr / public / schedulr.h < prev    next >
Encoding:
C/C++ Source or Header  |  1998-04-08  |  13.8 KB  |  336 lines
  1. /* -*- Mode: C; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*-
  2.  *
  3.  * The contents of this file are subject to the Netscape Public License
  4.  * Version 1.0 (the "NPL"); you may not use this file except in
  5.  * compliance with the NPL.  You may obtain a copy of the NPL at
  6.  * http://www.mozilla.org/NPL/
  7.  *
  8.  * Software distributed under the NPL is distributed on an "AS IS" basis,
  9.  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the NPL
  10.  * for the specific language governing rights and limitations under the
  11.  * NPL.
  12.  *
  13.  * The Initial Developer of this code under the NPL is Netscape
  14.  * Communications Corporation.  Portions created by Netscape are
  15.  * Copyright (C) 1998 Netscape Communications Corporation.  All Rights
  16.  * Reserved.
  17.  */
  18.  
  19. /*** schedulr.h *****************************************************
  20.  
  21.   The scheduling service allows clients to specify a time or range
  22.   of times at which a particular event is to occur. These events,
  23.   specified as callback functions, execute in their own thread and
  24.   can be set up to occur repeatedly or as a one-shot deal.
  25.  
  26.   Full HTML-based specifications for the operation of the scheduler,
  27.   including a complete API reference, are checked in to this
  28.   directory as schedulr.htm.  The information given there is a
  29.   superset of the comments in this file.
  30.  
  31.   $Revision: 3.1 $
  32.   $Date: 1998/03/28 03:36:00 $
  33.  
  34.  *********************************************************************/
  35.  
  36. #ifndef schedulr_h___
  37. #define schedulr_h___
  38.  
  39. #include <prcvar.h>
  40. #include <prlock.h>
  41. #include <prtime.h>
  42. #include <prtypes.h>
  43. #include <prthread.h>
  44.  
  45. /*********** Types **********/
  46.  
  47. typedef void *SchedulerPtr;
  48.  
  49. /*
  50.     All Scheduler APIs (with the exception of SchedulerStart) require a reference
  51.     to a scheduler instance in the form of a reference of type SchedulerPtr.  A
  52.     SchedulerPtr is returned from SchedulerStart, and its value is used as a handle
  53.     for a scheduler.  The structure referenced by a SchedulerPtr should be considered
  54.     an opaque entity; do not directly manipulate any data referenced by a
  55.     SchedulerPtr reference.
  56. */
  57.  
  58. typedef enum SchedulerErr {
  59.     SCHED_ERR_BEGIN = -5,
  60.     SCHED_ERR_BAD_EVENT = -5,
  61.     SCHED_ERR_BAD_TIME,
  62.     SCHED_ERR_BAD_PARAMETER,
  63.     SCHED_ERR_OUT_OF_MEMORY,
  64.     SCHED_ERR_INVALID_SCHEDULER,
  65.     SCHED_ERR_NOERR = 0,
  66.     SCHED_WARN_EVENTS_DROPPED,
  67.     SCHED_WARN_END = 1
  68. } SchedulerErr;
  69.  
  70. /*
  71.     Most APIs for the scheduler return a SchedulerErr type.  SchedulerErr is a typedef
  72.     for a signed integer value; zero is defined as no error (successful operation).
  73.     Negative values are errors (could not complete operation), and positive values are
  74.     warnings (operation completed with comments). All functions (even those which below
  75.     indicate that they "cannot fail") can return a ERR_SCHEDULER_INVALID if the passed
  76.     in scheduler reference is NULL. 
  77. */
  78.  
  79. typedef struct  _SchedulerTime {
  80.     PRUint32    repeating;        /* 0 = not repeating, otherwise seconds to add to base time for next time */
  81.     PRInt32        range;            /* Range must be a positive number of seconds */
  82.     PRTime        baseTime;
  83.     PRTime        start;
  84.     PRTime        end;
  85. } SchedulerTime;
  86.  
  87. /*
  88.     In order to instruct the scheduler to execute an event at a particular time, clients
  89.     specify a scheduled time expressed in a SchedulerTime structure.  The SchedulerTime
  90.     structure has values which correspond to the event's firing time (baseTime), and a
  91.     start and end time from which the event is valid (start and end, respectively).  
  92.     Additionally, SchedulerTime specifies a range, which acts as a randomization value
  93.     within which the event's scheduled time can "drift," and a repeating interval, both
  94.     of whch are expressed in seconds.
  95.  
  96.     See schedulr.htm for more information on how events are sscheduled.
  97. */
  98.  
  99. typedef void *SchedFuncDataPtr;
  100. typedef void (PR_CALLBACK *SchedFuncPtr)(SchedulerPtr pScheduler, PRUint32 eventID,
  101.                                          SchedFuncDataPtr pData);
  102.  
  103. /*
  104.     SchedFuncPtr is a prototype for the function which is called when the
  105.     scheduler fires an event.  The function returns nothing and accepts
  106.     three parameters, a reference to the scheduler from which the event
  107.     was dispatched, the event ID which identifies the event that executed
  108.     the function and an arbitrary data argument passed in at event creation.
  109.     The data argument is opaque to the scheduler and can be used by clients
  110.     to transmit or store state information, etc.  The function is called
  111.     asynchronously in its own thread, which terminates when the function exits.
  112. */
  113.  
  114. typedef PRInt32 SchedObsType;
  115.  
  116. #define    SCHED_OBSERVE_ADD        1
  117. #define    SCHED_OBSERVE_FIRE        2
  118. #define    SCHED_OBSERVE_REMOVE    4
  119. #define    SCHED_OBSERVE_PAUSE        8    /* not implemented */
  120. #define    SCHED_OBSERVE_RESUME    16    /* not implemented */
  121.  
  122. typedef void *SchedObsDataPtr;
  123. typedef void (PR_CALLBACK *SchedObsPtr)(SchedulerPtr pScheduler, PRUint32 observerID,
  124.                                         SchedObsDataPtr pData, SchedObsType type,
  125.                                         PRUint32 eventID, const char *eventName, 
  126.                                         SchedFuncDataPtr pEventData);
  127.  
  128. /*
  129.     Observer callbacks are specified using the prototype given as
  130.     SchedObsPtr.  When an event is added or removed from the
  131.     scheduler, or when an event fires, each observer who has registered
  132.     with that instance of the scheduler receives a notification
  133.     message.  The function returns nothing and receives information
  134.     on the event that triggered the notification (its id, name, and event
  135.     data), what kind of operation (add, remove, fire.) occurred, and
  136.     the id and data associated with the specific observer.  Both data
  137.     pointers are opaque to the scheduler.  The event data passed in
  138.     (pEventData) is the actual data pointer for the event, not a copy,
  139.     so observers must be aware that changing the information referred
  140.     to in pEventData may have unexpected results.  Additionally, because
  141.     there is no type information associated with pEventData, observers
  142.     must take particular care when making assumptions about the structure
  143.     or usage of pEventData.
  144. */
  145.  
  146.  
  147. /*********** Public APIs **********/
  148.  
  149. NSPR_BEGIN_EXTERN_C
  150.  
  151. PR_EXTERN(SchedulerPtr)
  152. SchedulerStart(void);
  153.  
  154. /*
  155.     Creates and initializes an instance of the scheduler.  SchedulerStart
  156.     creates a new (local) NSPR thread in which to run the instance
  157.     of the scheduler and returns a reference to a newly created scheduler
  158.     object.  This object is required for all calls to the scheduler API.
  159.     The newly created scheduler object is immediately ready to register and
  160.     dispatch events.  SchedulerStart allocates only enough memory for the
  161.     scheduler object itself; any supplementary data structures including the
  162.     event and observer queues are allocated when they are first referenced by
  163.     EventAdd or ObserverAdd.  If the thread can not be created or memory can
  164.     not be allocated, SchedulerStart returns NULL.  In order to properly
  165.     cleanup, SchedulerStop() should be called when the scheduler is to cease
  166.     operation. 
  167. */
  168.  
  169. PR_EXTERN(SchedulerErr)
  170. SchedulerStop(SchedulerPtr pScheduler);
  171.  
  172. /*
  173.     SchedulerStop halts scheduling of the specified scheduler instance,
  174.     deletes any memory referenced by the scheduler's event and observer
  175.     queues, and frees the instance of the Scheduler.  After calling
  176.     SchedulerStop, the instance of the scheduler referenced by the specified
  177.     SchedulerPtr is invalid and must not be used.  SchedulerStop can not fail
  178.     and will always return a successful result code. 
  179. */
  180.  
  181. PR_EXTERN(SchedulerErr)
  182. SchedulerPause(SchedulerPtr pScheduler);
  183.  
  184. /*
  185.     SchedulerPause causes the scheduler to cease firing events.  Pausing the
  186.     scheduler does not affect the the addition of new events to the scheduling
  187.     queue, nor does it prevent management of the observer list.  While the
  188.     scheduler is paused, any events scheduled to fire will be held in the
  189.     queue until the scheduler's operation is resumed with SchedulerResume.  
  190.     Calling SchedulerPause multiple times will have no effect beyond the first;
  191.     SchedulerPause can not fail and will always return a successful result code. 
  192. */
  193.  
  194. PR_EXTERN(SchedulerErr)
  195. SchedulerResume(SchedulerPtr pScheduler);
  196.  
  197. /*
  198.     SchedulerResume reverses the effect of a previous SchedulerPause call.
  199.     Events that did not fire while the scheduler queue was paused will
  200.     immediately fire, unless their scheduled end time (expiration) has passed,
  201.     in which case those items are removed from the queue.  Items removed from
  202.     the queue in this way cause an event deletion notification to be sent to
  203.     the scheduler's observers.  All other conditions, including sending
  204.     SchedulerResume to a scheduler which has not been paused will always
  205.     return a successful result code. 
  206.  
  207.     Pausing and resuming the scheduler is not reference counted; if multiple
  208.     threads have paused the scheduler, the first to resume it will cause the
  209.     scheduler to start actively processing events. 
  210. */
  211.  
  212.  
  213. PR_EXTERN(SchedulerErr)
  214. SchedulerAddEvent(SchedulerPtr pScheduler,
  215.                                PRUint32 *pEventID,
  216.                                const char *szName,
  217.                                SchedulerTime *pTime,
  218.                                SchedFuncPtr function,
  219.                                SchedFuncDataPtr pData);
  220.  
  221. /*
  222.     SchedulerAddEvent adds an event to the scheduler's event queue.  A
  223.     client which wishes to add an event needs to specify a time at which
  224.     the event should fire, a function to call when the time occurs, and
  225.     any amount of data which will be passed to the specified function at
  226.     the time that the event is fired.  A client may also supply a user-visible
  227.     name with which to identify the event.  Note that this name is not used by
  228.     the scheduler at all and may be NULL if no user-visible name is desired.
  229.     Both the time and name are copied into the scheduler's internal structures,
  230.     so the memory referenced by these events may be released after making this call. 
  231.  
  232.     If successful, SchedulerAddEvent adds the event to the event queue, assigns
  233.     a unique event ID which can be used to later refer to this specific event,
  234.     and returns a successful result code.  If NULL is passed in as the reference
  235.     to the pEventID, an event ID is still generated, but the client will be unable
  236.     to change or delete the event in the future.  Note that event IDs are unique
  237.     only to a particular scheduler instance; they are not guaranteed to be globally
  238.     unique across scheduler instances. 
  239.  
  240.     SchedulerAddEvent can fail for a number of reasons.  The most common is lack of
  241.     memory.  If the event queue needs to be created or expanded in size to accomodate
  242.     the new event, the scheduler will fail, returning SCHED_ERR_OUT_OF_MEMORY, and will
  243.     return 0 as the eventID.  Event addition will also fail if the time specified is
  244.     invalid, is outside the bounds specified by the event's start and end times,
  245.     or if the given range is negative (SCHED_ERR_BAD_TIME); or if a NULL value is given
  246.     for the function (SCHED_ERR_BAD_PARAMETER).
  247.  
  248.     See schedulr.htm for more detailed information, including the mechanism for
  249.     notifying observers.
  250. */
  251.  
  252.  
  253. PR_EXTERN(SchedulerErr)
  254. SchedulerRemoveEvent(SchedulerPtr pScheduler, PRUint32 eventID);
  255.  
  256. /*
  257.     SchedulerRemoveEvent removes a previously added event from the scheduler's
  258.     event queue.  The event to remove is specified by its eventID, previously
  259.     assigned by SchedulerAddEvent.  If the specified event ID is invalid, the
  260.     scheduler will return aan error, SCHED_ERR_BAD_EVENT, and no operation will
  261.     be performed. 
  262.  
  263.     See schedulr.htm for more detailed information, including the mechanism for
  264.     notifying observers.
  265. */
  266.  
  267. PR_EXTERN(SchedulerErr)
  268. SchedulerAddObserver(SchedulerPtr pScheduler,
  269.                      PRUint32 *pObserverID,
  270.                      SchedObsType type,
  271.                      SchedObsPtr function,
  272.                      SchedObsDataPtr pData);
  273.  
  274. /*
  275.     SchedulerAddObserver adds an observer to the specified scheduler's
  276.     observer list. An observer is a function which is called when the
  277.     scheduler adds, removes, or fires an event.  Which of these actions
  278.     trigger a notification for a given observer is specified in the
  279.     observer's type, which is a bitfield made up of the values specified
  280.     under SchedObsType, above.
  281.  
  282.     Like the corresponding AddEvent function, above, adding an observer
  283.     causes the scheduler to generate a unique observerID, which can later
  284.     be used to remove the observer.  Also like AddEvent, the observerID
  285.     is unique only within a scheduler instance.  ObserverIDs and EventIDs
  286.     are not interchangeable; their namespace may overlap.  Therefore, it's
  287.     important that the caller keep track of which identifiers represent
  288.     events and which represent observers. If NULL is passed in for the
  289.     observerID, an observer ID is generated, but it is not returned to
  290.     the caller. 
  291.  
  292.     SchedulerAddObserver can fail if memory can not be allocated to
  293.     store the observer or create the observer queue, or if the function
  294.     specified is NULL.  In each failure case, the observerID returned is
  295.     undefined.
  296.  
  297.     See schedulr.htm for more detailed information on observers and the
  298.     observer notification process.
  299. */
  300.  
  301. PR_EXTERN(SchedulerErr)
  302. SchedulerRemoveObserver(SchedulerPtr pScheduler, PRUint32 observerID);
  303.  
  304. /*
  305.     SchedulerRemoveObserver removes an observer from the scheduer's
  306.     observer list.  That observer no longer receives notification
  307.     messages and the scheduler frees any memory it has allocated
  308.     to track the specified observer.  If no observer with the given
  309.     ID exists, the function returns SCHED_ERR_BAD_PARAMETER, and no
  310.     operation is performed. 
  311. */
  312.  
  313. #ifdef DEBUG
  314.  
  315. PR_EXTERN(void)
  316. Sched_FormatEventTime(char *output, int len, SchedulerTime *pTime);
  317.  
  318. /*
  319.     Available only in DEBUG mode, this function takes a schedulerTime
  320.     and creates a string representation of it, suitable for displaying
  321.     in a debug message.  The string it returns, the first len characters
  322.     of which are copied into output, is of the format:
  323.  
  324.     {time} on {date} +/- {range} seconds, repeating every {repeat} seconds},
  325.     beginning on {start} and stopping on {end}
  326.  
  327.     The algorithm is smart enough to substitue appropriate language for
  328.     non-repeating and never-ending events.
  329. */
  330.  
  331. #endif
  332.  
  333. NSPR_END_EXTERN_C
  334.  
  335. #endif
  336.