/*
 * $Id: idle.txt,v 1.2 2004/12/01 00:51:22 peterrees Exp $
*/

/*  $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.
 *
 *      For altering the way the CPU is released see HB_IDLESLEEPMSEC()
 *      and HB_IDLEWAITNOCPU()
 *
 *  $SEEALSO$
 *      HB_IDLEADD(),HB_IDLEDEL(),HB_IDLESTATE(),HB_IDLESLEEPMSEC(),
 *      HB_IDLEWAITNOCPU()
 *  $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(),HB_IDLESLEEPMSEC(),HB_IDLEWAITNOCPU()
 *  $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(),HB_IDLESLEEPMSEC(),HB_IDLEWAITNOCPU()
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      HB_IDLESTATE()
 *  $CATEGORY$
 *      The idle states
 *  $ONELINER$
 *      Evaluates a single background task and calls the garbage collector.
 *  $SYNTAX$
 *      HB_IDLESTATE( bIndefinite )
 *  $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.
 *
 *      See description of hb_idleState() "C" function below for
 *      details of bIndefinite parameter
 *
 *  $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(),HB_IDLESLEEPMSEC(),HB_IDLEWAITNOCPU()
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      hb_idleState()
 *  $CATEGORY$
 *      The idle states
 *  $ONELINER$
 *      Evaluates a single background task and calls the garbage collector.
 *  $SYNTAX$
 *      void hb_idleState( BOOL bIndefinite );
 *  $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.
 *
 *      The argument bIndefinite is passed onto hb_releaseCPU(). This
 *      determines if the operating system WaitMessage() function is used
 *      for the Sleep state. See HB_IDLEWAITNOCPU(),
 *
 *      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(),HB_IDLESLEEPMSEC(),
 *      HB_IDLEWAITNOCPU()
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      HB_IDLESLEEPMSEC()
 *  $CATEGORY$
 *      The idle states
 *  $ONELINER$
 *      Allows tuning of the number of MilliSeconds to Sleep during idle state
 *  $SYNTAX$
 *      HB_IDLESLEEPMSEC( <nMilliSeconds> ) --> nMilliSecondsPrevious
 *  $ARGUMENTS$
 *      <nMilliSeconds> is the number of milli-seconds to sleep during each
 *      hb_idlestate() call
 *  $RETURNS$
 *      <nMilliSecondsPrevious> the number of milli-seconds of sleep time currently
 *      set ( before being reset by this call if <nMilliSeconds> is passed )
 *
 *  $DESCRIPTION$
 *      This function allows you to tune the sleep time on the platform you are
 *      using to optomise CPU usage. It is particularly useful on a multi-user
 *      system such as Linux or Windows Terminal Server where the minimum amount
 *      of background processing is desirable
 *  $EXAMPLES$
 *      ? HB_IDLESLEEPMSEC()
 *      nOldMSec := HB_IDLESLEEPMSEC( 50 )
 *      INKEY(10)
 *      HB_IDLESLEEPMSEC( nOldMSec )
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      Harbour extension
 *  $PLATFORMS$
 *      All
 *  $FILES$
 *      source/rtl/idle.c
 *  $SEEALSO$
 *      HB_IDLEADD(),HB_IDLEDEL(),HB_IDLESTATE(),HB_IDLEWAITNOCPU(),
 *      HB_IDLESLEEPMSEC()
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      HB_IDLEWAITNOCPU()
 *  $CATEGORY$
 *      The idle states
 *  $ONELINER$
 *      Allows most efficient idle sleep state to be used by operating system
 *  $SYNTAX$
 *      HB_IDLEWAITNOCPU( <bNewState> ) -->  bOldState
 *  $ARGUMENTS$
 *      <bNewState> is .T. or .F.. If .T. then hb_releaseCPU() will use the OS
 *      efficient idle sleep state - but only if implemented on that platform
 *  $RETURNS$
 *      <bOldState> the state before being reset by this call
 *
 *  $DESCRIPTION$
 *      This function tells hb_releaseCPU() to use the most efficient sleep state
 *      so that the minimum CPU cycles are wasted. If idle tasks have been added
 *      with HB_IDLEADD() then the setting of this state will be ignored. The
 *      setting will only by used with INKEY() when called with INKEY( 0 )
 *  $EXAMPLES$
 *      ? HB_IDLEWAITNOCPU()
 *      bOldState := HB_IDLEWAITNOCPU( .T. )
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      Harbour extension
 *  $PLATFORMS$
 *      All
 *  $FILES$
 *      source/rtl/idle.c
 *  $SEEALSO$
 *      HB_IDLEADD(),HB_IDLEDEL(),HB_IDLESTATE(),HB_IDLEWAITNOCPU()
 *  $END$
 */
