- 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.
- 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.166Up 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.
