memlog-init

Arguments: &key size width stop start wait yield-rate yield

This function initializes the current memory log with possibly new values for size and width. The return value is the new state of the initialized current log, or nil if nothing was done.

If the wait argument is non-nil, wait until the current log becomes available in the required state. If the wait argument is a number, wait that many seconds and if the time runs out, return nil. The default is to wait up to one second; this delay should be sufficient if an active log is in the middle of a logging call. If the wait argument is nil, return nil if the log is not in the required state.

When the stop argument is is non-nil (the default), stop logging when logging is active. Once logging is stopped, any current entries are discarded and the log is initialized. If the stop argument is nil, the log must already be stopped or nil is returned.

The start argument specifies the state of the current memory log after this operation:

• nil -- Leave the log in the :stopped state. This is the default.
• :cond -- Leave the log in the same state that was in effect on entry.
• other non-nil -- Leave the log in the :ready state.

The size argument specifes the maximum number of entries in the log. When the maximum is reached, older entries are overwritten with newer entries. If the size is not specified, the most recently used size continues in effect. The default size is 1000.

The width argument specifies the number of data values in each entry. If the width is not specified, the most recently used width continues in effect. The default width is 4.

All the memory locking operations must synchronize their behavior on a lock in memory. Spinning on the lock is most efficient in an SMP architecture, but when there are more threads than processors, spinning may be counterproductive. If a lock cannot be acquired in N attempts, the memlog operations yield to another thread and try again for N attempts. The yield-rate argument specifies a value for N. The default is 5.

The yield argument is tested by the memlog call only. If non-nil, the default, then one yield is performed if necessary to obtain a lock on the log object. If nil, then no yield call is made at all. Thus if the log is initialized with yield-rate=1 and yield=nil, a log entry will be made only when the log is available immediately; this is the least disruptive setting of the memory log. The skipped count returned by memlog-state increases as the waiting in memlog is made more restrictive.

See Memlog: A Facility for Minimally Intrusive Monitoring of Complex Application Behavior in smp.htm for more information.

See multiprocessing.htm for general information on multiprocessing in Allegro CL.

Copyright (c) 1998-2019, Franz Inc. Oakland, CA., USA. All rights reserved.
This page is new in the 10.0 release.
Created 2019.8.20.