Index | | | Related pages | | | Classes | | | Functions | | | Entities | | | Function Sets | | | Groups |
Support for script-based garbage collection strategies. more...
gcEnable | Turns automatic GC feature on or off. |
gcGetParams | Requests immediate check of garbage. |
gcPerform | Requests immediate check of garbage. |
gcSetThreshold | Turns automatic GC feature on or off. |
gcSetTimeout | Turns automatic GC feature on or off. |
The standard collector strategy (be it set up by the Falcon interpreter or by embedding applications) is adequate for average scripts.
However, some script meant to start from command line and dealing with time critical data may find the action of the garbage collector too intrusive. In example the GC may occuur at the wrong time. Other times, calculation intensive programs may generate a lot of data that they know in advance can be never garbaged during some period. In those case, having GC to scan periodically the allocated memory for released blocks is evidently a useless waste of time.
Finally, some complex scripts may even provide their own collection strategy, based on memory pattern usage that they know in advance. Starting the collection loop at time intervals, provided the memory allocation has grown at a certain rate, or hasn't grown for a certain time, may be a fitting strategy for some scripts.
A sensible usage of the garbage collection feature may boost performance of calculation and memory intensive scripts by order of degrees, and may be essential in time critical applications where some part of the process has to be performed as fast as possible.
Consider that some of the functions listed in this section may not be always available. Some embedding application may decide to turn some or all of them off for security reasons, as a malevolent script may crash an application very fast by turning off automatic GC check-and-reclaim feature and then creating a great amount of garbage. Also, the loop maximum execution time control is not present by default in Falcon command line, as the time-deterministic version of the garbage collector is sensibly slower, and it would be useless to the vast majority of the scripts.
Turns automatic GC feature on or off.
gcEnable( mode ) | |
mode | true to turn automatic GC on, false to turn it off. |
Virtual machines and some heavy garbage generating functions call periodically a function that checks for the level of allocated memory to have reached a critical point. When there is too much allocated memory of uncertain status, a garbage collecting loop is started.
By setting gcEnable to off, this automatic control is skipped, and allocated memory can grow up to physical process limits (or VM memory limit constraints, if provided). Setting this value to true will cause VM to perform memory control checks again with the usual strategy.
In case the script is sure to have generated a wide amount of garbage, it is advisable to call explicitly gcPerform() before turning automatic GC on, as the “natural” collection loop may start at any later moment, also after several VM loops.
Requests immediate check of garbage.
gcGetParams( [amem], [aitm], [lmem], [litm], [sth], [cth], [to] ) | |
amem | Amount of allocated memory. |
aitm | Amount of allocated items. |
lmem | Amount of alive memory. |
litm | Amount of alive items. |
sth | Currently set scan threshold. |
cth | Currently set collect threshold. |
to | Currently set collection timeout. |
This function retreives several statistical data and settings from the virtual machine memory manager. To retreive a parameter, pass a variable by reference, and pass nil in place of uninteresting parameters; in example, if wishing to recover the amount of alive memory and items:
aliveItems = 0 aliveMemory = 0 gcGetParams( nil, nil, $aliveMemory, $aliveItems )
Extra unneeded informations may just be ignored.
The value of the alive memory and items is reliable only after (actually, soon after) a gcPerform() call. The data is also stored by automatic GC loops invoked by the VM, but the scripts have no mean to know when they are performed. It is reasonable to suppose that the information is still not available if the values returned are both 0.
Both alive and allocated item count refers to those items that are actually stored in the memory manager. In fact, not every falcon item being available to the program will require garbage collection; only complex and deep items are accounted (mainly objects, strings, arrays and dictionaries).
The informations returned by this function may be used by scripts both for debugging purpose and to build their own collection strategy.
Requests immediate check of garbage.
gcPerform( [bForce] ) | |
bForce | If true, force collection of unused memory. |
Returns: | true if the gc has been actually performed, false otherwise. |
Performs immediately a garbage collection loop. All the items the script is managing are checked, and the memory they occupy is stored for later reference; the findings of the perform loop may be retrieved by the gcGetParams function. If the memory that is found unreferenced is below the memory reclaim threshold level, the function returns immediately false. Otherwise, a reclaim loop is performed and some memory gets cleared, and the function returns true.
If bForce is set to true, all the unused memory is immediately reclaimed, without taking into consideration the reclaim threshold.
See gcSetThreshold function for a in-depth of thresholds and memory constraints.
Turns automatic GC feature on or off.
gcSetThreshold( [scanTh], [collectTh] ) | |
scanTh | Amount of memory (in Kb) that triggers garbage scan. |
collectTh | Amount of memory (in Kb) that triggers garbage collection. |
This function sets the garbage collection threshold levels that start automatic GC loop. They are both optional; if nil is provided in place of one of them, that value is ignored (and stays at it was before).
The scanTh parameter determines when the automatic check the VM performs triggers a collection loop. When the allocated memory is below the scanTh level, nothing happens; when it is above, a collection loop is started.
When the VM determines how much memory is garbage, it checks that value against the collectTh level. A reclaim loop is started only if the detected free memory is more than collectTh bytes.
While scanTh value is not used if gcEnable is turned to off, collectTh level will still determine if the claim loop is worth to be taken also in case of explicit gcPerform calls from scripts.
The GC level does not take into consideration the real amount of memory that the objects are using, but the memory they report to the VM when they are created or modified.
After a GC is performed, the threshold levels are automatically adjusted so that GC collection checks and reclaims are not performed too often. The adjustment may change on a per VM basis; the default is to set the scanTh to the double of the memory that was found actually used, without changing the collectTh.
Default scanTh is very strict (1MB in this version); this level has the advantage to scale up fast in case of huge scripts while still being big enough to let the vast majority of control/embedded scripts to run without GC hindrance for their whole life.
Turns automatic GC feature on or off.
gcSetTimeout( msTimeout ) | |
msTimeout | Amount of memory (in Kb) that triggers garbage scan. |
This function sets the maximum time a collection loop may take, expressed in milliseconds. A timeout of 0 means "infinite".
This functionality is turned off by default. It must be explicitly activated by requesting it at the Falcon command line interpreter, or in case of embedding applications, it must be explicitly provided to the VM that is hosting the script.
This is for two reasons: mainly, checking for time constraints is itself a time consuming operation, especially when compared to the atomic operations that a GC loop usually performs. Secondly, a script using this feature may crash the host application very soon once environmental condition changes.
Considering the fact that without a complete GC loop used memory will never decrease, it's easy to see that a strict time constraint may prevent a full GC loop to ever take place. Even if the time is wide enough under normal circumstances (i.e. 100ms), if the script is to run ONCE on a heavy used CPU it may end up to be unable to perform the GC loop in the specified time, causing the next loops to be penalized, and possibly to never be able again to complete the collection under the given constraints.
If a script and the hosting program are willing to use this feature, the time constraints must be used only when it is really needed; they must be periodically turned off (by setting the timeout to 0) or possibly not used at all.
Of course, this is valid only for the time-constraint aware default GC provided by the Falcon API. Embedders are free to implement progressive GCs that may actually perform partial scanning in given time constraints. The "three-colors" garbage collector is a classical example. As all the GC strategies providing this feature are intrinsically less efficient than a monolithic all-or-nothing approach, and as they turn to be useful only in a very small category of applications (usually not delegated to scripting languages), Falcon does not provide any of them (for now).
However, as the embedders may find this hook useful, it is provided here in the core module, where it interfaces directly with a property on the base class handling memory and garbage: MemPool.
Index | | | Related pages | | | Classes | | | Functions | | | Entities | | | Function Sets | | | Groups |