4.42 Memory Management

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.

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.

set_prolog_stack(+Stack, +KeyValue)

Set a parameter for one of the Prolog runtime stacks. Stack is one of local, global, trail or argument. The table below describes the Key(Value) pairs. Value can be an arithmetic integer expression. For example, to specify a 2 GB limit for the global stack, one can use:

?- set_prolog_stack(global, limit(2*10**9)).

Current settings can be retrieved with prolog_stack_property/2.

limit(+Bytes)

Set the limit to which the stack is allowed to grow. If the specified value is lower than the current usage a permission_error is raised. If the limit is larger than supported, the system silently reduces the requested limit to the system limit.

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 spare stack 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.

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/4.

prolog_stack_property(?Stack, ?KeyValue)

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