# The "w" Package

These routines are meant to provide support for work functions. Work functions are similar to threads in that they allow background processing to be done, but require no threading support from the Operating System. Work functions are only executed while the application would otherwise be idle. NOTE: THIS PACKAGE IS WORK IN PROGRESS. THE INTERFACE MAY CHANGE IN THE NEXT RELEASE, POSSIBLY WITHOUT NOTICE.

Library: karma
Link With: -lkarma

#### Functions

w_test_supported | Test if application supports work functions.
w_register_support | Register support for work functions.
w_unregister_support | Unregister support for work functions.
w_register_notify_func | Register new work function callback.
w_work_to_be_done | Test for pending work functions waiting to be called.
w_do_work | Do some work.
w_register_func | Register a work function.
w_unregister_func | Unregister a work function.

#### Prototype Functions

w_PROTO_new_func | New work function callback.
w_PROTO_work_func | Work function.

#### Tables

w_PRIORITIES | List work function priorities

## Functions

flag w_test_supported ()

This routine will determine if work functions have been supported by the application.

Parameters:

This function takes no parameters

Returns: TRUE if work functions are supported, else FALSE.
Multithreading Level: Unsafe

void w_register_support ()

This routine will inform the package that the application will support work functions. This routine may only be called once unless an intervening call to <w_unregister_support> is made.

Parameters:

This function takes no parameters

Returns: Nothing.
Multithreading Level: Unsafe

#### EXPERIMENTAL FUNCTION: subject to change without notice

void w_unregister_support ()

This routine will inform the package that the application no longer supports work functions. This routine may only be called once unless an intervening call to <w_register_support> is made.

Parameters:

This function takes no parameters

Returns: Nothing.
Multithreading Level: Unsafe

void w_register_notify_func (void (*func) (void *info), void *info)

This routine will register a routine which is called whenever a new work function is registered.

Parameters:

- func : The function that is called when a new work function is registered. The prototype function is w_PROTO_new_func.
- info : The initial arbitrary information pointer.

Returns: A KCallbackFunc object. On failure, the process aborts.
Multithreading Level: Unsafe

flag w_work_to_be_done ()

This routine will determine if there are any pending work functions waiting to be called.

Parameters:

This function takes no parameters

Returns: TRUE if any work functions are pending, else FALSE.
Multithreading Level: Unsafe
Note:

- Disabling support for work functions via <w_unregister_support> has no effect on this function.

flag w_do_work ()

This routine will call any pending work functions. The work function at the top of the list is called once only.

Parameters:

This function takes no parameters

Returns: TRUE if more work is left to be done, else FALSE.
Multithreading Level: Unsafe

KWorkFunc w_register_func (flag (*func) (void **info), void *info, unsigned int priority)

This routine will register a work function. The work function at the top of the list is the one that is always called. Only when the work function at the top of the list is unregistered will the next work function be called.

Parameters:

- func : The routine to be called. The prototype function is w_PROTO_work_func.
- info : The initial arbitrary work function information pointer.
- priority : The priority level of the work function. See w_PRIORITIES for a list of legal values.

Returns: A KWorkFunc object. On failure, the process aborts.
Multithreading Level: Unsafe

void w_unregister_func (KWorkFunc wf)

This routine will unregister a work function. The second function in the list will moved to the top of the list. A work function cannot unregister itself in this manner.

Parameters:

- wf : The KWorkFunc object.

Returns: Nothing.
Multithreading Level: Unsafe

## Prototype Functions

void w_PROTO_new_func (void *info)

This routine is called whenever a new work function is registered.

Parameters:

- info : An arbitrary information pointer.

Returns: Nothing.
Multithreading Level: Unsafe

flag w_PROTO_work_func (void **info)

This routine is called to perform some work.

Parameters:

- info : A pointer to the arbitrary work function information pointer.

Returns: TRUE if the work function should be called again, else FALSE indicating that the work function is to be unregistered.
Multithreading Level: Unsafe

## Tables

w_PRIORITIES List work function priorities

Name | Meaning
KWF_PRIORITY_HIGHEST | Place function at top of list, any work | functions registered while this one is running | will be placed second in the list
KWF_PRIORITY_HIGH | Place function at top of list, any work | functions registered while this one is running | will be placed at the top of the list
KWF_PRIORITY_LOWEST | Place function at bottom of the list

Back to Karma Home Page