make-sharable-lock

Arguments: &key name max-shared yield-rate recursive-p safe-p auto-unlock-p constructor

This function returns a fresh instance of a sharable-lock.

The name argument must be a string or nil. The name is used in status and error messages.

The max-shared argument must be an integer greater than zero; it specifies the maximum number of simultaneous shared users allowed at any moment. The default value is 20. The size of the instance is proportional to this number. Values as high as 1000 still perform reasonably well, but much larger values may degrade performance noticably.

The yield-rate argument must be an integer greater than zero; it specifies how often a spin loop should yield. The default value is 5. Most of the low-level locking in SMP code is done with spin loops testing control bits. Such loops are very effective for short delays since they do not involve any operating system delays. However, if longer delays can occur, especially when the number of active threads is greater than the number of available processors, then spin loops can consume large amounts of cpu time with very little benefit. When a value of n is specified for yield rate, sharable-lock spin loops yield control every n-th iteration so that other threads may run and possibly release the needed resource sooner. If the yield-rate is specified as :never, then no yield is done at all.

The recursive-p argument specifies the behavior when a lock is locked recursively or repeatedly in the same thread. The value can be specified as a list containing any of the keywords below.

A value of nil, ie an empty list, prevents any recursive or repeated locking.

A non-nil value allows recursive or repeated locking from the same thread. Each locking call increments a counter and unlock calls decrement the counter. The lock is actually released when the count is zero. Although recursive or repeated locking is labeled with a mode, it does not actually change the state of the lock in any way; any recursive code operates in the same locking environment as the outermost or initial locking call.

• :exclusive: allows an exclusive locking call to succeed when an exclusive lock is already held in the same thread.
• :shared: allows a shared locking call to succeed when a shared lock is already held in the same thread.
• :downgrade: allows a shared locking call to succeed when an exclusive lock is already held in the same thread. This is a potentially dangerous use of the lock since the outer exclusive locking code may have made partial inconsistent changes to some data object.
• :upgrade: allows an exclusive locking call to succeed when a shared lock is already held in the same thread. This use is both dangerous and of questionable utility since the strength of the lock has not changed. Any modifications made in the upgrade code will be seen by any number of shared users assuming unmutability of the data.

The default setting is t to denote the list (:exclusive :shared). The default is thus to allow recursive or repeated access of the same mode.

If shared access is used for read-only access to a data object, recursive access is safe and meaningful. If exclusive access is used to make multiple related changes to a data object, recursive access may be meaningful, but the recursive acesses must be reviewed for possible interference.

Note also that separate counters are maintained for uses of the macros with-shared-lock and with-exclusive-lock, and uses of the sharable-lock-lock function. A call to sharable-lock-unlock cannot release a lock obtained with one of the macros.

The safe-p argument specifies the behavior if an attempt is made to unlock a lock that is already unlocked. The default value is t. When the value is non-nil, an error is signaled if an attempt is made to unlock a lock that is already unlocked. When the value is nil, the attempt is ignored silently.

The auto-unlock-p argument specifies the behavior if the locking process is terminated without releasing the lock. The default value is nil. When the value is nil, nothing is done. When the value is non-nil, a lock held by a terminated process is automatically released when competition for the lock occurs.

The constructor argument specifies the constructor used in creating a sharable-lock instance. The default constructor creates an instance of the sharable-lock struct. A user-defined sub-class must be a struct that includes sharable-lock.

See Sharable locks in smp.htm.

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

Copyright (c) 1998-2019, Franz Inc. Oakland, CA., USA. All rights reserved.
The object described on this page has been modified in the 9.0 release; see the Release Notes.
Created 2019.8.20.