4.43.1 Garbage collection

garbage_collect

Invoke the global and trail stack garbage collector. Normally the garbage collector is invoked automatically if necessary. Explicit invocation might be useful to reduce the need for garbage collections in time-critical segments of the code. After the garbage collection trim_stacks/0 is invoked to release the collected memory resources.

garbage_collect_atoms

Reclaim unused atoms. Normally invoked after agc_margin (a Prolog flag) atoms have been created. On multithreaded versions the actual collection is delayed until there are no threads performing normal garbage collection. In this case garbage_collect_atoms/0 returns immediately. Note that there is no guarantee it will ever happen, as there may always be threads performing garbage collection.

blob_type_property(?Type, ?Property)

True when the registered blob type Type has Property. With Type unbound this enumerates the registered types; note that a type is registered on first use, so a type whose library has not yet created a blob is not enumerated. Defined properties are below; only gc_margin(Units) can be set, using set_blob_type/2.

unique

text

nocopy

wchar

The PL_BLOB_* flags of the type, present only if set. See section 12.4.10.1.

rank(Integer)

Position of the type in the standard order of terms. The order between types is assigned as they are registered and is thus not stable over runs.

padding(Bytes)

Zero bytes added after the data of a copied blob.

gc_margin(Units)

Request atom garbage collection once this many units of Type have become candidates for it. A blob counts with the length it was created with, so the unit is bytes for text and for types that report what they retain, and instances for types that report 1. 0, the default for every type, leaves Type to agc_margin, which counts atoms regardless of what they keep alive. Setting agc_margin to zero disables atom garbage collection and no type budget overrides that. See section 12.4.10.3.

unregistered(Units)

How much of Type is currently a candidate for collection, in the same units. Compare against gc_margin(Units) to see how far behind collection is.

non_garbage(Units)

How much the last collection found to be live and therefore discounted. The next request needs gc_margin(Units) on top of this, which is what stops a type whose blobs are live from asking repeatedly.

live(Count)

space(Units)

The number of blobs of this type that exist and what they hold. Unlike counting current_blob/2 these are maintained as blobs come and go and do not scan the atom table.

set_blob_type(+Type, +Property)

Set Property of the registered blob type Type. Only gc_margin(Units) can be set; see blob_type_property/2. A type normally declares its budget in C when it defines its PL_blob_t (see section 12.4.10.3); this predicate tunes a running system.

garbage_collect_clauses

Reclaim retracted clauses. During normal operation, retracting a clause implies setting the erased generation to the current generation of the database and increment the generation. Keeping the clause around is both needed to realise the logical update view and deal with the fact that other threads may be executing the clause. Both static and dynamic code is processed this way.^{167Up to version 7.3.11, dynamic code was handled using reference counts.}.

The clause garbage collector (CGC) scans the environment stacks of all threads for referenced dirty predicates and at which generation this reference accesses the predicate. It then removes the references for clauses that have been retracted before the oldest access generation from the clause list as well as the secondary clauses indexes of the predicate. If the clause list is not being scanned, the clause references and ultimately the clause itself is reclaimed.

The clause garbage collector is called under three conditions, (1) after reloading a source file, (2) if the memory occupied by retracted but not yet reclaimed clauses exceeds 12.5% of the program store, or (3) if skipping dead clauses in the clause lists becomes too costly. The cost of clause garbage collection is proportional with the total size of the local stack of all threads (the scanning phase) and the number of clauses in all ‘dirty’ predicates (the reclaiming phase).

set_prolog_gc_thread(+Status)

Control whether or not atom and clause garbage collection are executed in a dedicated thread. The default is true. Values for Status are true, false and stop. The latter stops the gc thread but allows is to be recreated lazily. This is use by e.g., fork/1 to avoid forking a multi-threaded application. See also gc_thread.

trim_stacks

Release stack memory resources that are not in use at this moment, returning them to the operating system. It can be used to release memory resources in a backtracking loop, where the iterations require typically seconds of execution time and very different, potentially large, amounts of stack space. Such a loop can be written as follows:

loop :-
        generator,
            trim_stacks,
            potentially_expensive_operation,
        stop_condition, !.

The Prolog top-level loop is written this way, reclaiming memory resources after every user query. See also trim_heap/0 and thread_idle/2.

set_prolog_stack(+Stack, +KeyValue)

Set a parameter for one of the Prolog runtime stacks. Stack is one of local, global or trail. The table below describes the Key(Value) pairs.

Current settings can be retrieved with prolog_stack_property/2.

min_free(+Cells)

Minimum amount of free space after trimming or shifting the stack. Setting this value higher can reduce the number of garbage collections and stack-shifts at the cost of higher memory usage. The amount is reported and specified in cells. A cell is 4 bytes in the 32-bit version and 8 bytes on the 64-bit version. See address_bits. See also trim_stacks/0 and debug/0.

low(+Cells)

factor(+Number)

These two figures determine whether, if the stacks are low, a stack shift (expansion) or garbage collection is performed. This depends on these two parameters, the current stack usage and the amount of stack used after the last garbage collection. A garbage collection is started if used > factor × lastused + low.

spare(+Cells)

All stacks trigger overflow before actually reaching the limit, so the resulting error can be handled gracefully. The spare stack is used for print_message/2 from the garbage collector and for handling exceptions. The default suffices, unless the user redefines related hooks. Do not specify large values for this because it reduces the amount of memory available for your real task.

Related hooks are message_hook/3 (redefining GC messages), prolog_trace_interception/4 and prolog_exception_hook/5.

prolog_stack_property(?Stack, ?KeyValue)

True if KeyValue is a current property of Stack. See set_prolog_stack/2 for defined properties.

The total space limit for all stacks is controlled using the prolog flag stack_limit.