with-locked-structure

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

This macro expands into code that waits until the executing process acquires control of the structure 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:

• struct: a form that is evaluated once to get the object to be locked. The object must be 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 (mp:without-scheduling . body)
  • :without-interrupts to get the equivalent of (excl:without-interrupts . body)
  • :atomically to get the equivalent of (excl:atomically . body)
  • (omitted) to get object-locking code like smp. This may be inefficient or even problematic in a non-smp lisp.
• typecheck: if specified as nil, the generated code does not include an explicit typecheck of the structure object. Otherwise, (whether omitted or specified non-nil) the generated code checks that struct is a synchronizing structure before trying to lock it.
• 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 at the end of the body code.

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 9.0 page.
Created 2015.5.21.