xHarbour Reference Documentation > Function Reference

HB_BackGroundAdd()

Adds a new background task.

Syntax

HB_BackGroundAdd( <bAction>, [<nMillisecs>], [<lActive>] ) --> nTaskHandle

Arguments

<bAction>

This is a codeblock that will be executed in the background.

<nMillisecs>

This is a numeric value specifying the number of milliseconds after which the task is executed. The default value is zero,which means that the background task is executed each time background processing is invoked.

<lActive>

The default value of <lActive> is .T. (true) causing <bAction> being checked for immediate background activation. Passing .F. (false) adds the task to the internal task list but does not execute it until it is activated with HB_BackGroundActive().

Return

The function returns a numeric task handle that must be preserved for other background processing functions, such as HB_BackGroundDel().

Description

Function HB_BackGroundAdd() adds the passed codeblock to the list of background tasks that will be executed concurrently to the main program. There is no limit for the number of background tasks.

Background task processing must be activated using the command SET BACKGROUND TASKS ON. Background tasks are processed sequentially until a SET BACKGROUND TASKS OFF is issued or an idle state is encountered. The idle state is the state of the xHarbour virtual machine (VM) when it waits for user input from the keyboard or the mouse. The VM enters idle state during Inkey() calls. All applications that do not use Inkey() function calls can signal the idle state with a call to the HB_IdleState() function.

Note:  to avoid interruption of background processing during idle states, an idle task must be defined like HB_IdleAdd( {||HB_BackGroundRun()} ).

An alternative for background tasks is provided with threads. Refer to function StartThread() for running parts of an application simultaneously in multiple threads.

Info

See also:	HB_BackGroundActive(), HB_BackGroundDel(), HB_BackGroundReset(), HB_BackGroundRun(), HB_BackGroundTime(), HB_ExecFromArray(), HB_IdleAdd(), StartThread()
Category:	Background processing , xHarbour extensions
Source:	rtl\bkgtsks.c
LIB:	xhb.lib
DLL:	xhbdll.dll

Example

// The example uses a regular background task to display the time
// once in a second while MemoEdit() is active. To ensure continuous
// display while MemoEdit() waits for user input, an idle task is
// defined which enforces background task processing.

   PROCEDURE Main
      LOCAL nTask, nIdle

      DispOutAtSetPos( .F. )
      SET BACKGROUND TASKS ON

      nIdle := HB_IdleAdd( {|| HB_BackGroundRun() } )

      nTask := HB_BackGroundAdd( {|| ShowTime() }, 1000 )

      MemoEdit( MemoRead( "Test.prg" ), 1, 0, MaxRow()-2, MaxCOl() )

      HB_BackGroundDel( nTask )
      HB_IdleDel( nIdle )
   RETURN


   PROCEDURE ShowTime()
      DispoutAt( MaxRow(), MaxCol()-7, Time() )
   RETURN