sharable-lock-lock

Arguments: sharable-lock mode &key yield-rate timeout recursive-p

Acquire a sharable-lock in the specified mode.

If the lock was acquired, The single value returned is one of the keywords:

• :locked: the lock was acquired in the requested mode.
• :recursive: the lock is already owned in the requested mode. An additional access of the same mode is recorded for this thread.
• :downgrade: the lock is already held in exclusive mode, but a shared access from the same thread is recorded as well.
• :upgrade: the lock is already held in shared mode; and additional shared access from the same thread is recorded.

If the call fails to acquire the lock, two values are returned. The first value is nil to indicate failure. The second value is a keyword that describes the reason:

• :timeout: a timeout occurred before the lock could be acquired.
• :exclusive: an exclusive locker prevented access.
• :shared: one or more shared lockers prevented access. An exclusive lock is delayed by any shared lockers. A shared lock is delayed if max-shared lockers are already locking.
• :busy: one or more other lockers prevented access but it was not possible to tell which case. Another attempt to acquire the lock is likely to give another answer.
• :recursive-error: a recursive locking attempt is not allowed because of the recursive-p setting.
• :downgrade-error: a downgrade is not allowed because of the recursive-p setting.
• :upgrade-error: an upngrade is not allowed because of the recursive-p setting.
• :interrupting: the locking call is in a process-interrupt function that has interrupted another locking attempt in a place that does not allow any recursion. Another attempt is likely to succeed, but the attempt must be made with a new call to process-interrupt. Looping or waiting in the process-interrupt function is futile and counterproductive.
• :downgrade-state-error: probably an implementation error
• :upgrade-state-error: probably an implementation error

The mode argument must be one of the keywords :shared or :exclusive.

The yield-rate argument, if specified, must be a positive integer, or the keyword :never. The specified value overrides the value in the lock instance. If the argument is omitted, or specified as nil, than the value in the lock instance is used.

The timeout argument, if specified, must be a non-negative number of seconds. The value determines how long the program will wait if the lock is not immediately available. A timeout value of zero specifies that that the lock must be available immediately only.

The recursive-p argument may be used to override the recursion specification in the sharable-lock instance. If omitted, nil or :default, the value in the lock instance is used. Otherwise, the value must be t, one of the keywords allowed in make-sharable-lock, or a list of these keywords. If the recursive-p setting does not allow a recursive or repeated call, the behavior is determined by the timeout argument. If the timeout argument is omitted, or non-zero, an error of type sharable-lock-recursion-error is signaled; otherwise one of the above keywords is returned as the second value.

When the timeout value is greater than zero, and a timeout occurs, the second value is :timeout.

When the timeout value is zero, the lock is acquired only if there is no delay. If there would be a delay, the second value is one of the keywords listed above.

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.