appCORE - coreAppStop()

NAME

coreAppStop() -- request the application's main dispatch thread to shutdown.

SYNOPSIS

include "appcore.h"

int coreAppStop()

DESCRIPTION

The coreAppStop() function is used to stop the main dispatch thread. If appCORE is in the 'RUN' state, a stop control message is sent to the central dispatch thread. If the state is already 'STOPPING' no message is sent, as the dispatch thread is already shutting down. All messages already in the dispatch queue are still processed. Messages added to the queue after the stop message shall not be processed, but rather flushed during thread exit cleanup. After the stop message is processed, the user's Shutdown function is executed, if defined.

If adhering to the standard appCORE design patterns, the function coreAppWaitOnStop() is normally called after the stop request to wait for the main dispatch thread to exit. This function performs a thread join with the dispatch thread. coreAppWaitOnStop() provides for an orderly, predictable program shutdown order.

PARAMETERS

None.

RETURN VALUE

If successful, coreAppStop() returns 0. On failure it returns a value of -1 and sets errno to one of the following:

errno Value	Condition
EIDRM	The main dispatch thread has already stopped.
ECANCELED	appCORE not in the run state.
ENOMEM	Out of message resources.

MULTI-THREAD SAFETY LEVEL

MT-safe.