Macro | Package: excl | ToC | DocOverview | CGDoc | RelNotes | FAQ | Index | PermutedIndex
| Allegro CL version 9.0 Unrevised from 8.2 to 9.0. 8.2 version

## with-locked-object

Arguments: (object &key type block non-smp typecheck timeout) &body body

This macro expands into code that waits until the executing process acquires control of the object, then evaluates the forms in the body as an implicit progn. It then releases control of the object and returns whatever values the last form in the body returned.

The arguments are:

- object: a form that is evaluated once to get the object to be locked. the object must be an instance of `lockable-object` or of a subclass of `lockable-object` unless the type argument is included and specifies otherwise. Object can also be a class object (an instance of `standard-class`). The instances of such classes are not necessarily lockable; the class would need to inherit from `lockable-object` for the instances to be lockable.
- type: can be one of the following
  - `:clos` (the default): the object form must evaluate to an instance of `lockable-object` or of a subclass of `lockable-object`.
  - `:struct`: the object form must evaluate to an instance of `synchronizing-structure` or of a subtype of `synchronizing-structure`.
- block: used for special internal functions. Users should not specify this.
- non-smp: what code to generate in a non-smp lisp. Legal values are:
  - `:without-scheduling` to get the equivalent of `(without-scheduling . body)`
  - `:without-interrupts` to get the equivalent of `(with-delayed-interrupts . body)`
  - `:atomically` (only valid when the type argument is `:struct`) to get the equivalent of `(fast-and-clean . body)`
  - [omitted]: to get object-locking code like SMP. This may be inefficient or even problematic in a non-smp lisp, and is not allowed in the 8.1 patch.
- typecheck: if specified as `nil`, the generated code does not include an explicit typecheck of the object. If specified as non-`nil` the generated code checks that the object is of the appropriate type. If typecheck is ommitted, the type check code is generated unless the type argument is `:clos` (explicitly or by default)
- timeout: If specified, the value must be `nil` or a real number. If `nil` (or unspecified), the body will be evaluated if and when the lock is acquired. A value greater than 0 specifies a timeout of that many seconds; when the timeout occurs before the lock is acquired, the body is not evaluated and the entire form evaluates to `nil`. A value less than or equal to 0 specifies an immediate timeout; the body is evaluated only if the lock can be acquired with no delay. If the body itself return `nil`, one cannot then tell from the return value whether the body executed or not. See mp:with-process-lock for an example where timing out causes additional code to run which can make clear whether the body did or did not execute.

It is not an error for a process that already owns an object to try to lock it again. When this happens, the object is not released until the outermost lock form is exited.

The release of the object is performed in an unwind-protect cleanup form, so non-local exits from body are allowed.

See smp.htm and multiprocessing.htm for more information on this macro and on multiprocessing.

Copyright (c) 1998-2019, Franz Inc. Oakland, CA., USA. All rights reserved.
This page was not revised from the 8.2 page.
Created 2012.5.30.

|  | ToC | DocOverview | CGDoc | RelNotes | FAQ | Index | PermutedIndex
| Allegro CL version 9.0 Unrevised from 8.2 to 9.0. 8.2 version