/*
 * $Id: idle.txt 6073 2003-07-13 16:24:32Z alex_degarate $
 */

/*
 * Las siguientes partes son derechos adquiridos de sus autores individuales.
 * www - http://www.harbour-project.org
 *
 * Copyright 2000 Brian Hays <bhays@abacuslaw.com>
 * Documentacin en Ingls de:
 *              Readme for Idle state, HB_IDLEADD(), HB_IDLEDEL()
 *              HB_IDLESTATE(), hb_idleState()
 *
 * Copyright 2000 Alejandro de Grate <alex_degarate@hotmail.com>
 * Documentacin en Espaol de:
 *              Leame para Estado Ocioso, HB_IDLEADD(), HB_IDLEDEL()
 *              HB_IDLESTATE(), hb_idleState()
 *
 * Vea doc/license.txt por los trminos de la licencia.
 *
 */


/*  $DOC$
 *  $FUNCNAME$
 *      Estado Ocioso
 *  $CATEGORY$
 *      Documento
 *  $ONELINER$
 *      Archivo Lame para Estado Ocioso
 *  $DESCRIPTION$
 *      El estado de espera  ocioso es el estado de la mquina virtual de
 *      Harbour cuando esta espera por una accin del usuario a travs del
 *      teclado  el mouse. El estado ocioso ocurre actualmente durante
 *      las llamadas a INKEY(). Todas las funciones que no usen la funcin
 *      INKEY() pueden sealizar el estado ocioso con una llamada a la
 *      funcin Harbour HB_IDLESTATE()  hb_idleState() a nivel de lenguaje
 *      C.
 *
 *      Durante los estados ociosos, la mquina virtual llama al recolector
 *      de memoria y este puede llamar a acciones definidas por el usuario
 *      (tareas en segundo plano  background). Este tambin libera porciones
 *      del tiempo de la CPU para algunas plataformas deficientes que no son
 *      lo suficientemente inteligentes (Windows NT).
 *
 *      Por definicin de tareas en segundo plano vea las funciones:
 *       HB_IDLEADD() y HB_IDLEDEL().
 *
 *      Para llamar directamente a acciones en segundo plano vea la funcin:
 *      HB_IDLESTATE().
 *
 *      Para indicar el estado ocioso desde cdigo en lenguaje C vea la
 *      hb_idleState() en la API,
 *  $SEEALSO$
 *      HB_IDLEADD(),HB_IDLEDEL()
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      HB_IDLEADD()
 *  $CATEGORY$
 *      Estado Ocioso
 *  $ONELINER$
 *      Agrega tareas en segundo plano.
 *  $SYNTAX$
 *      HB_IDLEADD( <cbAccion> ) --> nHandle
 *  $ARGUMENTS$
 *      <cbAccion>  es un bloque de cdigo que ser ejecutado durante los
 *                  estados ociosos, No hay argumentos pasados a este bloque
 *                  de cdigo durante la evaluacin.
 *  $RETURNS$
 *      <nHandle>  El manejador (un valor entero) que identifica la tarea.
 *                 Este manejador puede ser usado para eliminar la tarea.
 *  $DESCRIPTION$
 *      HB_IDLEADD() agrega el pasado bloque de cdigo a las lista de tareas
 *      en segundo plano que sern evaluadas durante los estados ociosos.
 *      No hay un lmite para el nmero de tareas.
 *  $EXAMPLES$
 *      nTarea := HB_IDLEADD( {|| SayTime()} )
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      Extensin de Harbour, similar a la funcin FT_ONIDLE() disponible
 *      en la librera Nanforum.
 *  $PLATFORMS$
 *      Todas
 *  $FILES$
 *      El archivo fuente es ../source/rtl/idle.c
 *  $SEEALSO$
 *      HB_IDLEDEL(),HB_IDLESTATE()
 *  $END$
 */


/*  $DOC$
 *  $FUNCNAME$
 *      HB_IDLEDEL()
 *  $CATEGORY$
 *      Estado Ocioso
 *  $ONELINER$
 *      Remueve tareas desde la lista de tareas en segundo plano.
 *  $SYNTAX$
 *      HB_IDLEDEL( <nHandle> ) --> xAccion
 *  $ARGUMENTS$
 *      <nHandle> es el identificador de la tarea devuelto por la funcin
 *                HB_IDLEADD().
 *  $RETURNS$
 *      Retorna <xAccion> igual a NIL si un manejador no vlido es pasado
 *  $DESCRIPTION$
 *      La funcin HB_IDLEDEL() remueve la accin asociada con el identi-
 *      ficador pasado desde la lista de tareas en segundo plano.
 *      El identificador debera ser el valor retornado por la llamada
 *      previa a la funcin HB_IDLEADD().
 *      Si la tarea especificada est definida, entonces el codeblock es
 *      retornado, de otro modo el valor NIL es retornado.
 *  $EXAMPLES$
 *      nTarea := HB_IDLEADD( {|| SayTime()} )
 *      INKEY(10)
 *      cbAccion := HB_IDLEDEL( nTarea )
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      Extensin de Harbour
 *  $PLATFORMS$
 *      Todas
 *  $FILES$
 *      El archivo fuente es ../source/rtl/idle.c
 *  $SEEALSO$
 *      HB_IDLEADD(),HB_IDLESTATE()
 *  $END$
 */


/*  $DOC$
 *  $FUNCNAME$
 *      HB_IDLESTATE()
 *  $CATEGORY$
 *      Estado Ocioso
 *  $ONELINER$
 *      Evala una sola tarea en segundo plano y llama al recolector
 *  $SYNTAX$
 *      HB_IDLESTATE()
 *  $ARGUMENTS$
 *      Ninguno
 *  $RETURNS$
 *      NIL
 *  $DESCRIPTION$
 *      La funcin HB_IDLESTATE() solicita la recoleccin de memoria sin
 *      uso y ejecuta una nica tarea definida por el bloque de cdigo
 *      pasado con la funcin HB_IDLEADD(). Cada llamada a esta funcin
 *      evala una tarea diferente en el orden de la creacin de tareas.
 *      No hay argumentos pasados durante la evaluacin del bloque de
 *      cdigo.
 *      Esta funcin puede ser llamada con seguridad, an si no hay tareas
 *      definidas en segundo plano.
 *  $EXAMPLES$
 *      nTarea1 := HB_IDLEADD( {|| MuestreLaHora()} )
 *      nTarea2 := HB_IDLEADD( {|| SaveScreen()} )
 *
 *      DO WHILE( ! bTerminado )
 *         bTerminado := HagaAlgoMuyImportante()
 *         HB_IdleState()
 *      ENDDO
 *
 *      cbAccion := HB_IDLEDEL( nTarea1 )
 *      HB_IDLEDEL( nTarea2 )
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      Extensin de Harbour, similar a la funcin FT_IAMIDLE() disponible
 *      en la librera Nanforum.
 *  $PLATFORMS$
 *      Todas
 *  $FILES$
 *      El archivo fuente es ../source/rtl/idle.c
 *  $SEEALSO$
 *      HB_IDLEADD(),HB_IDLEDEL()
 *  $END$
 */


/*  $DOC$
 *  $FUNCNAME$
 *      hb_idleState()
 *  $CATEGORY$
 *      Estado Ocioso
 *  $ONELINER$
 *      Evala una sola tarea en segundo plano y llama al recolector
 *  $SYNTAX$
 *      void hb_idleState( void );
 *  $ARGUMENTS$
 *      Ninguno
 *  $RETURNS$
 *      Nada.
 *  $DESCRIPTION$
 *      La funcin hb_idleState() es una funcin en lenguaje C que solicita
 *      la recoleccin de memoria sin uso y ejecuta una sola tarea en
 *      segundo plano, definida por el bloque de cdigo pasado con la
 *      funcin HB_IDLEADD(). Esta tambin libera porciones de tiempo de
 *      CPU para aquellas plataformas que lo requieran.
 *
 *      Cada llamda a esta funcin evala una tarea diferente en el orden
 *      de la creacin de tareas. No hay argumentos pasados durante la
 *      evaluacin del bloque de cdigo.
 *
 *      Esta funcin puede ser llamada con seguridad, an si no hay tareas
 *      definidas en segundo plano.
 *
 *      Esta funcin es automticamente llamada desde la funcin INKEY().
 *  $STATUS$
 *      R
 *  $PLATFORMS$
 *      Todas
 *  $FILES$
 *      El archivo fuente es ../source/rtl/idle.c
 *  $SEEALSO$
 *      HB_IDLEADD(),HB_IDLEDEL(),HB_IDLESTATE()
 *  $END$
 */ 


