doc/master/low_memory

SYNOPSIS
        void low_memory(int what, int limitvalue, int memory, int reservestate)

DESCRIPTION
        This efun is called when there is a (potential) low-memory situation.
        Two different limits for the amount of allocated memory can be
        configured: a soft limit and a hard limit. If the soft limit is
        exceeded, the driver calls low_memory() but does nothing else.
        If the hard limit is exceeded, the driver calls low_memory() as well,
        but initiates a garbage collection directly after the call. The efun
        is called as well directly before a user-initiated garbage collection
        is started.

        <what> denotes the type of limit which was exceeded:
        - NO_MALLOC_LIMIT_EXCEEDED   (0)
            No limit was exceeded, but a garbage collection was requested by a
            call to garbage_collection() and it will begin right after
            low_memory() returns.
        - SOFT_MALLOC_LIMIT_EXCEEDED (1)
            The soft limit was exceeded.
        - HARD_MALLOC_LIMIT_EXCEEDED (2)
            The hard limit was exceeded. A garbage collection will begin right
            after low_memory() returns.

        <limit> specifies the numerical value of the limit which was exceeded.
        It is 0 in case of NO_MALLOC_LIMIT_EXCEEDED.

        <memory> specifies the amount of allocated memory right now.

        <reservestate> specifies the current state of the memory reserves of
        the driver. The states of the 3 different reserves are OR'ed together.
        - USER_RESERVE_AVAILABLE   (1)
          The user reserve is available.
        - MASTER_RESERVE_AVAILABLE (2)
          The master reserve is available.
        - SYSTEM_RESERVE_AVAILABLE (4)
          The system reserve is available.

        This efun might be used to inform users about the garbage collection
        and the expected long lag.

        Another possibility is to initiate a garbage collection deliberately
        at a suitable time (e.g. during the following night) after the soft
        limit was hit.

REMARKS
        If in a low_memory condition when the memory reserves have been used
        already and they could not be re-allocated after a garbage collection
        slow_shut_down() is called instead of calling this function again.

HISTORY
        Introduced in 3.3.719

SEE ALSO
        debug_info(E), garbage_collection(E), slow_shut_down(M), memory(C)
        malloc(D)