Harbour All Functions – H

HardCR

HBClass()

HB_ANSITOOEM()

hb_At

hb_cdpSelect

HB_ColorIndex

HB_DiskSpace

HB_EOL

HB_FEof

hb_FLock

hb_FUnlock

hb_gcAll
hb_gcAlloc
hb_gcCollectAll
hb_gcFree
hb_gcItemRef

hb_GetEnv

hb_HAllocate

hb_Hash
hb_HAutoAdd
hb_HBinary
hb_HCaseMatch
hb_HClone
hb_HCopy
hb_HDefault
hb_HDel
hb_HDelAt
hb_HEval
hb_HFill
hb_HGet
hb_HGetDef
hb_HHasKey
hb_HKeyAt
hb_HKeys
hb_HMerge
hb_HPairAt
hb_HPos
hb_HScan
hb_HSet

hb_HSetAutoAdd()
hb_HSetBinary() 
hb_HSetCaseMatch()

hb_HSort
hb_HValueAt
hb_HValues

hb_idleAdd
hb_idleDel
hb_idleState

hb_inetAddress
hb_inetCleanup
hb_inetClearError
hb_inetClearPeriodCallback
hb_inetClearTimeLimit
hb_inetClearTimeout
hb_inetClose
hb_inetConnect
hb_inetConnectIP
hb_inetCount
hb_inetCreate
hb_inetCRLF
hb_inetDataReady
hb_inetDGram
hb_inetDGramBind
hb_inetDGramRecv
hb_inetDGramSend
hb_inetErrorCode
hb_inetErrorDesc
hb_inetFD
hb_inetGetAlias
hb_inetGetHosts
hb_inetGetRcvBufSize
hb_inetGetSndBufSize
hb_inetInit
hb_inetIsSocket
hb_inetPeriodCallback
hb_inetPort
hb_inetRecv
hb_inetRecvAll
hb_inetRecvEndblock
hb_inetRecvLine
hb_inetSend
hb_inetSendAll
hb_inetServer
hb_inetSetRcvBufSize
hb_inetSetSndBufSize
hb_inetstatus
hb_inetTimeLimit
hb_inetTimeout

HB_IsByRef()

hb_keyPut

hb_langErrMsg
hb_langMessage
hb_langName
hb_langSelect

hb_mathErBlock
hb_mathErMode
hb_mathGetErrMode
hb_mathGetHandler
hb_mathGetLastError
hb_mathIsMathErr
hb_mathResetError
hb_mathSetErrMode
hb_mathSetHandler

hb_MemoRead
hb_MemoWrit

hb_RAt

hb_PIsByRef

hb_PValue

hb_SetKeyCheck
hb_SetKeyGet
hb_SetKeySave

hb_setListenerAdd

hb_setListenerNotify
hb_setListenerRemove

hb_SetMacro

hb_Translate

hb_ValToStr

Header

HexaToDec

hb_idleState()

HB_IdleState()

Evaluates a single background task and calls the garbage collector.

Syntax

      HB_IDLESTATE()

Arguments

None

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 )

Compliance

Harbour extension similar to FT_IAMIDLE() function available in NanForum library.

Platforms

All

Files

src/rtl/idle.c

Seealso

HB_IDLEADD(), HB_IDLEDEL()

hb_idleDel()

HB_IDLEDEL()

Removes the background task from the list of tasks.

Syntax

      HB_IDLEDEL( <nHandle> ) --> <bAction>

Arguments

<nHandle> is the identifier of the task returned by the HB_IDLEADD() function.

Returns

<bAction> 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 )
      bAction := hb_idleDel( nTask )

Compliance

Harbour

Platforms

All

Files

src/rtl/idle.c

Seealso

HB_IDLEADD(), HB_IDLESTATE()

hb_idleAdd()

HB_IDLEADD()

Adds the background task.

Syntax

      HB_IDLEADD( <bAction> ) --> nHandle

Arguments

<bAction> 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() } )

Compliance

Harbour extension similar to FT_ONIDLE() function available in NanForum library.

Platforms

All

Files

src/rtl/idle.c

Seealso

HB_IDLEDEL(), HB_IDLESTATE()

The Garbage Collector

The Garbage Collector

Readme for Harbour Garbage Collect Feature

Description

The garbage collector uses the following logic:

 – first collect all memory allocations that can cause garbage;
– next scan all variables if these memory blocks are still referenced.

Notice that only arrays, objects and codeblocks are collected because these are the only datatypes that can cause self-references (a[1]:=a) or circular references (a[1]:=b; b[1]:=c; c[1]:=a) that cannot be properly deallocated by simple reference counting.

Since all variables in harbour are stored inside some available tables (the eval stack, memvars table and array of static variables) then checking if the reference is still alive is quite easy and doesn’t require any special treatment during memory allocation. Additionaly the garbage collector is scanning some internal data used by harbour objects implementation that also stores some values that can contain memory references. These data are used to initialize class instance variables and are stored in class shared variables.

In special cases when the value of a harbour variable is stored internally in some static area (at C or assembler level), the garbage collector will be not able to scan such values since it doesn’t know their location. This could cause some memory blocks to be released prematurely. To prevent the premature deallocation of such memory blocks the static data have to store a pointer to the value created with hb_itemNew() function.

Example:

static HB_ITEM s_item; this item can be released by the GC
static PHB_ITEM pItem; this item will be maintained correctly pItem = hb_itemNew( hb_param( 1, IT_BLOCK ) );

However, scanning of all variables can be a time consuming operation. It requires that all allocated arrays have to be traversed through all their elements to find more arrays. Also all codeblocks are scanned for detached local variables they are referencing. For this reason, looking for unreferenced
memory blocks is performed during the idle states.

The idle state is a state when there is no real application code executed. For example, the user code is stopped for 0.1 of a second during Inkey(0.1) – Harbour is checking the keyboard only during this time. It leaves however quite enough time for many other background tasks. One such background task can be looking for unreferenced memory blocks.

Allocating memory

The garbage collector collects memory blocks allocated with hb_gcAlloc() function calls. Memory allocated by hb_gcAlloc() should be released with hb_gcFree() function.

The garbage collecting

During scanning of unreferenced memory the GC is using a mark & sweep algorithm. This is done in three steps:

1) mark all memory blocks allocated by the GC with unused flag;

2) sweep (scan) all known places and clear unused flag for memory blocks that are referenced there;

3) finalize collecting by deallocation of all memory blocks that are still marked as unused and that are not locked.

To speed things up, the mark step is simplified by swapping the meaning of the unused flag. After deallocation of unused blocks all still alive memory blocks are marked with the same ‘used’ flag so we can reverse the meaning of this flag to ‘unused’ state in the next collecting. All new or unlocked memory blocks are automatically marked as ‘unused’ using the current flag, which assures that all memory blocks are marked with the same flag before the sweep step will start. See hb_gcCollectAll() and hb_gcItemRef()

Calling the garbage collector from harbour code

The garbage collector can be called directly from the harbour code. This is usefull in situations where there is no idle states available or the application is working in the loop with no user interaction and there is many memory allocations. See hb_gcAll() for explanation of how to call this function from your harbour code.

Seealso

hb_gcAlloc(), hb_gcFree(), hb_gcCollectAll(), hb_gcItemRef(), hb_gcAll(), hb_idleState()