globally-accessible

globally-accessible Macro

Summary

A wrapper setf place that ensures earlier stores are visible to other threads before storing into the inner place.

Package

system

Signature

globally-accessible place => value

Arguments

place⇩

A generalized reference form as described in section 5.1.1 Overview of Places and Generalized Reference of the Common Lisp Hyperspec.

Values

value

Any Lisp object.

Description

The macro globally-accessible expands to place. The effect of using (globally-accessible place) is the same as place, except when used inside setf or a related macro such as push or incf where it also ensures all stores are visible to other threads before modifying place. This includes all the stores that were made into the new value and, for a modifying macro or complex accessor, any stores that are done by the expansion.

See 19.3.5 Ensuring stores are visible to other threads for a full discussion when globally-accessible is needed.

When used with accessors that take a place as argument (getf, mask-field, ldb or cdr-assoc), globally-accessible needs to be used around innermost place, rather than the accessor, for example:

(setf (getf (sys:globally-accessible *a-global-symbol*)
            key)
      value)

rather than:

(setf  ; WRONG
   (sys:globally-accessible
    (getf *a-global-symbol* key))
   value)

globally-accessible tries to avoid ensuring all stores when it is possible to avoid it, for example when used inside pushnew if the value is already in the list.

Notes

You do not need to use globally-accessible when any of the following apply:

place can be accessed only by the same thread that stores into it (so it is not globally accessible). This is the common situation for stores.
Access to place (both read and writes) is synchronized between threads, normally by a lock but maybe by some other synchronization mechanism. This is the preferred way to access globally accessible cells.
The store is done by one of: (setf gethash), vector-push, vector-push-extend, (setf symbol-function), (setf macro-function) and the hash-table or vector containing the globally accessible cell was not created as single-threaded.

In other cases (globally accessible cells which are read without synchronization), you probably need globally-accessible. See 19.3.5 Ensuring stores are visible to other threads for exact details.