192 lines
5.5 KiB
Plaintext
192 lines
5.5 KiB
Plaintext
/*
|
|
* $Id$
|
|
*/
|
|
|
|
/* $DOC$
|
|
* $FUNCNAME$
|
|
* The idle states
|
|
* $CATEGORY$
|
|
* Document
|
|
* $ONELINER$
|
|
* Read me file for Idle States
|
|
* $DESCRIPTION$
|
|
* The idle state is the state of the harbour virtual machine when it
|
|
* waits for the user input from the keyboard or the mouse. The idle
|
|
* state is entered during INKEY() calls currently. All applications
|
|
* that don't use INKEY() function call can signal the idle states with
|
|
* the call of HB_IDLESTATE() function (or hb_idleState() on C level).
|
|
*
|
|
* During idle states the virtual machine calls the garbage collector and
|
|
* it can call user defined actions (background tasks). It also releases
|
|
* the CPU time slices for some poor platforms that are not smart enough
|
|
* (Windows NT).
|
|
*
|
|
* For defining the background tasks see the HB_IDLEADD() and HB_IDLEDEL()
|
|
* functions.
|
|
*
|
|
* For direct call for background actions see HB_IDLESTATE() function.
|
|
*
|
|
* For signaling the idle state from C code see the hb_idleState()
|
|
* API function.
|
|
* $SEEALSO$
|
|
* HB_IDLEADD(),HB_IDLEDEL()
|
|
* $END$
|
|
*/
|
|
|
|
/* $DOC$
|
|
* $FUNCNAME$
|
|
* HB_IDLEADD()
|
|
* $CATEGORY$
|
|
* The idle states
|
|
* $ONELINER$
|
|
* Adds the background task.
|
|
* $SYNTAX$
|
|
* HB_IDLEADD( <cbAction> ) --> nHandle
|
|
* $ARGUMENTS$
|
|
* <cbAction> is a codeblock that will be executed during idle states.
|
|
* There are no arguments passed to this codeblock during evaluation.
|
|
* $RETURNS$
|
|
* <nHandle> The handle (an integer value) that identifies the task. This
|
|
* handle can be used for deleting the task.
|
|
* $DESCRIPTION$
|
|
* HB_IDLEADD() adds a passed codeblock to the list of background
|
|
* tasks that will be evaluated during the idle states. There is no
|
|
* limit for the number of tasks.
|
|
* $EXAMPLES$
|
|
* nTask := HB_IDLEADD( {|| SayTime()} )
|
|
* $STATUS$
|
|
* R
|
|
* $COMPLIANCE$
|
|
* Harbour extension similar to FT_ONIDLE() function available
|
|
* in NanForum library.
|
|
* $PLATFORMS$
|
|
* All
|
|
* $FILES$
|
|
* source/rtl/idle.c
|
|
* $SEEALSO$
|
|
* HB_IDLEDEL(),HB_IDLESTATE()
|
|
* $END$
|
|
*/
|
|
|
|
/* $DOC$
|
|
* $FUNCNAME$
|
|
* HB_IDLEDEL()
|
|
* $CATEGORY$
|
|
* The idle states
|
|
* $ONELINER$
|
|
* Removes the background task from the list of tasks.
|
|
* $SYNTAX$
|
|
* HB_IDLEDEL( <nHandle> ) --> xAction
|
|
* $ARGUMENTS$
|
|
* <nHandle> is the identifier of the task returned by the
|
|
* HB_IDLEADD() function.
|
|
* $RETURNS$
|
|
* <xAction> NIL if invalid handle is passed or a codeblock that was
|
|
* passed to HB_IDLEADD() function
|
|
* $DESCRIPTION$
|
|
* HB_IDLEDEL() removes the action associated with passed identifier
|
|
* from the list of background tasks. The identifer should be the
|
|
* value returned by the previous call of HB_IDLEADD() function.
|
|
*
|
|
* If specified task is defined then the codeblock is returned
|
|
* otherwise the NIL value is returned.
|
|
* $EXAMPLES$
|
|
* nTask := HB_IDLEADD( {|| SayTime()} )
|
|
* INKEY(10)
|
|
* cbAction := HB_IDLEDEL( nTask )
|
|
* $STATUS$
|
|
* R
|
|
* $COMPLIANCE$
|
|
* Harbour extension
|
|
* $PLATFORMS$
|
|
* All
|
|
* $FILES$
|
|
* source/rtl/idle.c
|
|
* $SEEALSO$
|
|
* HB_IDLEADD(),HB_IDLESTATE()
|
|
* $END$
|
|
*/
|
|
|
|
/* $DOC$
|
|
* $FUNCNAME$
|
|
* HB_IdleState()
|
|
* $CATEGORY$
|
|
* The idle states
|
|
* $ONELINER$
|
|
* Evaluates a single background task and calls the garbage collector.
|
|
* $SYNTAX$
|
|
* HB_IDLESTATE()
|
|
* $ARGUMENTS$
|
|
* None
|
|
* $RETURNS$
|
|
* NIL
|
|
* $DESCRIPTION$
|
|
* HB_IDLESTATE() requests the garbage collection and executes a
|
|
* single background task defined by the codeblock passed with
|
|
* HB_IDLEADD() function. Every call to this function evaluates a
|
|
* different task in the order of task creation. There are no
|
|
* arguments passed during a codeblock evaluation.
|
|
*
|
|
* This function can be safely called even if there are no background
|
|
* tasks defined.
|
|
* $EXAMPLES$
|
|
* nTask1 := HB_IDLEADD( {|| SayTime()} )
|
|
* nTask2 := HB_IDLEADD( {|| SaveScreen()} )
|
|
* DO WHILE( !bFinished )
|
|
* bFinished :=DOSomethingVeryImportant()
|
|
* HB_IdleState()
|
|
* ENDDO
|
|
* cbAction := HB_IDLEDEL( nTask1 )
|
|
* HB_IDLEDEL( nTask2 )
|
|
* $STATUS$
|
|
* R
|
|
* $COMPLIANCE$
|
|
* Harbour extension similar to FT_IAMIDLE() function available
|
|
* in NanForum library.
|
|
* $PLATFORMS$
|
|
* All
|
|
* $FILES$
|
|
* source/rtl/idle.c
|
|
* $SEEALSO$
|
|
* HB_IDLEADD(),HB_IDLEDEL()
|
|
* $END$
|
|
*/
|
|
|
|
/* $DOC$
|
|
* $FUNCNAME$
|
|
* hb_idleState()
|
|
* $CATEGORY$
|
|
* The idle states
|
|
* $ONELINER$
|
|
* Evaluates a single background task and calls the garbage collector.
|
|
* $SYNTAX$
|
|
* void hb_idleState( void );
|
|
* $ARGUMENTS$
|
|
* None
|
|
* $RETURNS$
|
|
* Nothing
|
|
* $DESCRIPTION$
|
|
* hb_idleState() is a C function that requests garbage collection and
|
|
* executes a single background task defined by the codeblock passed
|
|
* with HB_IDLEADD() function. It also releases the CPU time slices for
|
|
* platforms that require it.
|
|
*
|
|
* Every call for this function evaluates different task in the
|
|
* order of task creation. There are no arguments passed during
|
|
* codeblock evaluation.
|
|
*
|
|
* This function can be safely called even if there are no background
|
|
* tasks defined.
|
|
*
|
|
* This function is automatically called from the INKEY() function.
|
|
* $STATUS$
|
|
* R
|
|
* $PLATFORMS$
|
|
* All
|
|
* $FILES$
|
|
* source/rtl/idle.c
|
|
* $SEEALSO$
|
|
* HB_IDLEADD(),HB_IDLEDEL(),HB_IDLESTATE()
|
|
* $END$
|
|
*/
|