Scheduling C Library Functions

$Header: /cvsroot/aolserver/aolserver.com/docs/devel/c/index.html,v 1.1 2002/03/07 19:15:35 kriston Exp $

Ns_RegisterAtExit

Register an exit procedure.

Syntax

    
    typedef void (Ns_Callback) (void *context);

    Ns_ProcHandle Ns_RegisterAtExit(
    Ns_Callback *proc,
    void *context
    );

Description

The Ns_RegisterAtExit function registers proc as a function to call before AOLserver exits after all servers are shut down. The procedures are run in last-registered first-run order.



Ns_RegisterAtPreStartup

Register a procedure for pre-server startup

Syntax

    
    void* Ns_RegisterAtPreStartup (
    Ns_Callback* proc,
    void* arg
    );

Description

Register a procedure to be called just before the binder is terminated, prior to server startup. The return value is an opaque handle (which is currently not useful).



Ns_RegisterAtSignal

Register a procedure at HUP signal

Syntax

    
    void* Ns_RegisterAtSignal (
    Ns_Callback* proc,
    void* context
    );

Description

Register a callback to run when the HUP signal is received by the server.



Ns_RegisterAtStartup

Register a procedure for server startup

Syntax

    
    void* Ns_RegisterAtStartup (
    Ns_Callback* proc,
    void* context
    );

Description

Register a callback to run when the server is done starting up.



Ns_RegisterServerShutdown

Register a shutdown procedure for a server.

Syntax

    
    typedef void (Ns_Callback) (void *context);

    Ns_ProcHandle Ns_RegisterServerShutdown(
    char *hServer,
    Ns_Callback *proc,
    Ns_OpContext context
    );

Description

The Ns_RegisterServerShutdown function registers proc as a shutdown procedure on the specified server. The server calls all shutdown procedures before shutting down, in last-registered first-run order. The shutdown procedure takes the context as its sole argument. A shutdown procedure is often used to close or free a resource allocated by a module's initialization routine.



Ns_RegisterShutdown

Register a shutdown procedure.

Syntax

    
    typedef void (Ns_Callback) (void *context);

    Ns_ProcHandle Ns_RegisterShutdown(
    Ns_Callback *proc,
    void *context
    );

Description

The Ns_RegisterShutdown function registers proc as a shutdown procedure. The server calls all shutdown procedures before shutting down, in last-registered first-run order. The shutdown procedure takes the context as its sole argument. A shutdown procedure is often used to close or free a resource allocated by a module's initialization routine.



Ns_TclRegisterAtCreate

Register function for interpreter creation

Syntax

    
    int Ns_TclRegisterAtCreate (
    Ns_TclInterpInitProc* proc,
    void* arg
    );

Description

Register a procedure to be called when an interpreter is first created for a thread.



Ns_TclRegisterDeferred

Register a function for interpreter cleanup

Syntax

    
    void Ns_TclRegisterDeferred (
    Tcl_Interp *interpPtr ,
    Ns_TclDeferProc *deferProc ,
    void *contex
    );

Description

Register a procedure to be called when the interpreter is cleaned up.



Ns_ScheduleDaily

Schedule a procedure to run once a day

Syntax

    
    int Ns_ScheduleDaily(
    Ns_SchedProc *proc,
    void *context,
    int flags,
    int hour,
    int minute,
    Ns_SchedProc *cleanup
    );

Description

The Ns_ScheduleDaily function schedules the procedure (proc) to be run once a day at the specified time (hour and minute).

The proc is the scheduled procedure that will be run once a day. It is a function that takes the context and id of the schedule procedure. The id can be used in the Ns_UnscheduleProc procedure to stop the procedure from being called again. typedef void (Ns_SchedProc) (void *context, int id); The context is the context to pass to the scheduled procedure.

The possible flags are NS_SCHED_ONCE and NS_SCHED_THREAD. If you specify NS_SCHED_ONCE, the procedure will only be executed once on the specified day and time, and it will not be re-scheduled to execute again the next day. By default, the procedure is re-scheduled after every time it is executed.

If you specify NS_SCHED_THREAD, the procedure will run detached in a separate thread instead of using the one scheduled procedure thread used by all other scheduled procedures. You should use NS_SCHED_THREAD if the procedure will not return immediately. Note that if you use NS_SCHED_THREAD, and the procedure is still active the next time to run occurs, the next run is skipped instead of just delayed.

The hour can be an integer from 0 to 23, and the minute an integer from 0 to 59.

The cleanup procedure will be run once when the proc procedure is unscheduled.

Examples

   Run a procedure (MyProc) once in its own thread at 2:30 a.m.:
    Ns_ScheduleDaily(myProc, myCtx, NS_SCHED_ONCE | NS_SCHED_THREAD,
2, 30, NULL)

   



Ns_ScheduleProc

Schedule a procedure to run at specified intervals

Syntax

    
    int Ns_ScheduleProc(
    void (*proc) (),
    void *context,
    int fNewThread,
    int interval
    );

Description

The Ns_ScheduleProc function schedules the procedure proc to be run every interval seconds, with context as an argument. The flag fNewThread determines whether proc runs in its own thread. Ns_ScheduleProc returns an integer id for use in the Ns_UnscheduleProc function.

Note that the newer Ns_ScheduleProcEx function provides a superset of the functionality in Ns_ScheduleProc.



Ns_ScheduleProcEx

Schedule a procedure to run at specified intervals

Syntax

    
    int Ns_ScheduleProcEx(
    Ns_SchedProc *proc,
    void *context,
    int flags,
    int interval,
    Ns_SchedProc *cleanup
    );

Description

The Ns_ScheduleProcEx function schedules the procedure (proc) to be run at a specific time interval specified in seconds. Ns_ScheduleProcEx returns an integer id for use in the Ns_UnscheduleProc function.

The proc procedure is the scheduled procedure that will be run at each interval. It is a function that takes the context and id of the schedule procedure. The id can be used in the Ns_UnscheduleProc procedure to stop the procedure from being called again. typedef void (Ns_SchedProc) (void *context, int id); The context is the context to pass to the scheduled procedure.

The possible flags are NS_SCHED_ONCE and NS_SCHED_THREAD. If you specify NS_SCHED_ONCE, the procedure will only be executed once on the specified day and time, and it will not be re-scheduled to execute again. By default, the procedure is re-scheduled after every time it is executed.

If you specify NS_SCHED_THREAD, the procedure will run detached in a separate thread instead of using the one scheduled procedure thread used by all other scheduled procedures. You should use NS_SCHED_THREAD if the procedure will not return immediately. Note that if you use NS_SCHED_THREAD, and the procedure is still active the next time to run occurs, the next run is skipped instead of just delayed.

The interval is the number of seconds between runs of the procedure.

The cleanup procedure will be run once when the proc procedure is unscheduled.



Ns_ScheduleWeekly

Schedule a procedure to run once a week

Syntax

    
    int Ns_ScheduleWeekly(
    Ns_SchedProc *proc,
    void *context,
    int flags,
    int day,
    int hour,
    int minute,
    Ns_SchedProc *cleanup
    );

Description

The Ns_ScheduleWeekly function schedules the procedure (proc) to be run once a week on the specified day (day) at the specified time (hour and minute).

The proc procedure is the scheduled procedure that will be run once a week. It is a function that takes the context and id of the schedule procedure. The id can be used in the Ns_UnscheduleProc procedure to stop the procedure from being called again. typedef void (Ns_SchedProc) (void *context, int id); The context is the context to pass to the scheduled procedure.

The possible flags are NS_SCHED_ONCE and NS_SCHED_THREAD. If you specify NS_SCHED_ONCE, the procedure will only be executed once on the specified day and time, and it will not be re-scheduled to execute again the next week. By default, the procedure is re-scheduled after every time it is executed.

If you specify NS_SCHED_THREAD, the procedure will run detached in a separate thread instead of using the one scheduled procedure thread used by all other scheduled procedures. You should use NS_SCHED_THREAD if the procedure will not return immediately. Note that if you use NS_SCHED_THREAD, and the procedure is still active the next time to run occurs, the next run is skipped instead of just delayed.

The day can be an integer from 0 to 6, where 0 represents Sunday. The hour can be an integer from 0 to 23, and the minute an integer from 0 to 59.

The cleanup procedure will be run once when the proc procedure is unscheduled.



Ns_UnscheduleProc

Stop a scheduled procedure

Syntax

    
    void Ns_UnscheduleProc (
    int id
    );

Description

The Ns_UnscheduleProc function stops a scheduled procedure from executing again. The scheduled procedure to be stopped is identified by its id, which was returned by the Ns_Schedule* function that was used to schedule the procedure. It is safe to call Ns_UnscheduleProc from inside a scheduled procedure.



Ns_WaitForStartup

Block until server startup

Syntax

    
    int Ns_WaitForStartup (void);

Description

Block until server startup.