Generic Function | Package: mp | ToC | DocOverview | CGDoc | RelNotes | FAQ | Index | PermutedIndex
| Allegro CL version 9.0 Object described on page has changed in 9.0. 8.2 version

## 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.

|  | ToC | DocOverview | CGDoc | RelNotes | FAQ | Index | PermutedIndex
| Allegro CL version 9.0 Object described on page has changed in 9.0. 8.2 version