The atomics Reference Manual

Table of Contents

Next: , Previous: , Up: (dir)   [Contents][Index]

The atomics Reference Manual

This is the atomics Reference Manual, version 1.0.0, generated automatically by Declt version 2.4 patchlevel 1 "Will Decker" on Mon Jul 29 14:31:40 2019 GMT+0.


Next: , Previous: , Up: Top   [Contents][Index]

1 Introduction

## About Atomics
This is a library for access to atomic operation primitives such as compare-and-swap. It aims to be a rather thin layer over what the implementations offer.

## Currently Supported Implementations
The following implementations are fully or partially supported:

- Allegro
- CCL
- ECL
- LispWorks
- SBCL

For a detailed report on the capabilities, please see the documentation of the respective operators. If you think that an implementation should be added, or better supported, please file an "issue"(https://github.com/shinmera/atomics/issues) or a pull request with the necessary information.

If the library is unsupported, an error will be signalled on load. If an operation is unsupported, an error will be signalled on usage of the operator.

Next: , Previous: , Up: Top   [Contents][Index]

2 Systems

The main system appears first, followed by any subsystem dependency.


Previous: , Up: Systems   [Contents][Index]

2.1 atomics

Maintainer

Nicolas Hafner <shinmera@tymoon.eu>

Author

Nicolas Hafner <shinmera@tymoon.eu>

Home Page

https://shinmera.github.io/atomics/

Source Control

(:git "https://github.com/shinmera/atomics.git")

Bug Tracker

https://github.com/Shinmera/atomics/issues

License

zlib

Description

Portability layer for atomic operations like compare-and-swap (CAS).

Version

1.0.0

Dependency

documentation-utils

Source

atomics.asd (file)

Components

Next: , Previous: , Up: Top   [Contents][Index]

3 Files

Files are sorted by type and then listed depth-first from the systems components trees.


Previous: , Up: Files   [Contents][Index]

3.1 Lisp


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.1 atomics.asd

Location

atomics.asd

Systems

atomics (system)


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.2 atomics/atomics.lisp

Parent

atomics (system)

Location

atomics.lisp

Packages

atomics

Exported Definitions
Internal Definitions

no-support (function)


Previous: , Up: Lisp files   [Contents][Index]

3.1.3 atomics/documentation.lisp

Dependency

atomics.lisp (file)

Parent

atomics (system)

Location

documentation.lisp


Next: , Previous: , Up: Top   [Contents][Index]

4 Packages

Packages are listed by definition order.


Previous: , Up: Packages   [Contents][Index]

4.1 atomics

Source

atomics.lisp (file)

Nickname

org.shirakumo.atomics

Use List

common-lisp

Exported Definitions
Internal Definitions

no-support (function)


Next: , Previous: , Up: Top   [Contents][Index]

5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.


Next: , Previous: , Up: Definitions   [Contents][Index]

5.1 Exported definitions


Next: , Previous: , Up: Exported definitions   [Contents][Index]

5.1.1 Macros

Macro: atomic-decf PLACE &optional DELTA

Atomically decreases place by the specified delta.

Returns the value the place has been set to.

For restrictions, see ATOMIC-INCF.

See ATOMIC-INCF

Package

atomics

Source

atomics.lisp (file)

Macro: atomic-incf PLACE &optional DELTA

Atomically increases place by the specified delta.

Returns the value the place has been set to.

Restrictions apply to allowed PLACEs by implementation:

Allegro CCL ECL LispWorks SBCL
CAR X X X X X
CDR X X X X X
FIRST X X
REST X X
SVREF X X X X
AREF X
SYMBOL-VALUE X X X
SLOT-VALUE X* X* X*
MEMREF X
MEMREF-INT X
struct-slot X X* X* X X*
special-var X X X
custom X X X
global (SBCL) X*

Further restrictions apply:

# Allegro (EXCL:ATOMIC-INCF) See CAS

# CCL (CCL:ATOMIC-INCF-DECF) See CAS

# ECL (MP:ATOMIC-INCF) See CAS
- The places must store a FIXNUM.
- The addition is performed with modular arithmetic, meaning over- or underflows will wrap around.

# LispWorks (SYSTEM:ATOMIC-INCF) See CAS

# SBCL (SB-EXT:ATOMIC-INCF) - struct-slots must be of type SB-EXT:WORD.
- AREF only works on (SIMPLE-ARRAY SB-EXT:WORD (*)).
- Other places must be a FIXNUM.
- The addition is performed with modular arithmetic, meaning over- or underflows will wrap around.

See CAS

Package

atomics

Source

atomics.lisp (file)

Macro: atomic-update PLACE UPDATE-FN

Updates the PLACE with the value retrieved from UPDATE-FN

The UPDATE-FN is called with the old value of the PLACE and should return the new value to set the place to.
The PLACE and UPDATE-FN may be evaluated multiple times.

For restrictions that apply to the PLACE, see CAS.

See CAS

Package

atomics

Source

atomics.lisp (file)

Macro: cas PLACE OLD NEW

Perform a Compare-And-Swap.

Returns non-NIL if successful, NIL if not.
On success it is guaranteed that the PLACE has been set to the NEW value atomically, that is to say while the PLACE still had a value EQ to OLD. On failure the value of PLACE has most likely changed to one not EQ to OLD.

Restrictions apply to allowed PLACEs by implementation:

Allegro CCL ECL LispWorks SBCL
CAR X X X X
CDR X X X X
FIRST X X
REST X X
SVREF X X X X X
SYMBOL-PLIST X X X
SYMBOL-VALUE X X X X
SLOT-VALUE X* X* X* X*
MEMREF X
MEMREF-INT X
struct-slot X X* X* X X*
special-var X X X X
custom X X X

Further restrictions apply:

# Allegro (EXCL:ATOMIC-CONDITIONAL-SETF) - SLOT-VALUE can only be used for :INSTANCE and :CLASS allocated slots and the SLOT-VALUE-USING-CLASS protocol is ignored.
- struct-slot definitions must be available at compile-time.
- SYMBOL-VALUE accesses the dynamically bound value if it is dynamically bound, rather than the global value.

# CCL (CCL::CONDITIONAL-STORE) - struct-slot accesses only seem to work quite right for T-typed slots.

# ECL (MP:COMPARE-AND-SWAP) - If a slot is unbound, an error is signalled unless the OLD value is SI:UNBOUND. If the slot has any methods defined on SLOT-VALUE-USING-CLASS, the consequences are undefined.
- struct-slots must be defined with the :atomic-accessors option. See DEFSTRUCT for a portable wrapper.

# LispWorks (SYSTEM:COMPARE-AND-SWAP) - SLOT-VALUE can only be used for :INSTANCE and :CLASS allocated slots and will not work with SLOT-VALUE-USING-CLASS.

# SBCL (SB-EXT:CAS) - If a slot is unbound, an error is signalled unless the OLD value is SB-PCL:+SLOT-UNBOUND+. If the slot has methods defined on SLOT-VALUE-USING-CLASS or SLOT-BOUNDP-USING-CLASS, the consequences are undefined.
- struct-slot types must be either FIXNUM or T.

Package

atomics

Source

atomics.lisp (file)

Macro: defstruct NAME &rest SLOTS

Wrapper around CL:DEFSTRUCT to portably define atomically modifiable structures.

See CL:DEFSTRUCT

Package

atomics

Source

atomics.lisp (file)


Next: , Previous: , Up: Exported definitions   [Contents][Index]

5.1.2 Generic functions

Generic Function: operation CONDITION

Returns the unsupported operation or NIL on entirely unsupported implementations.

See IMPLEMENTATION-NOT-SUPPORTED

Package

atomics

Methods
Method: operation (CONDITION implementation-not-supported)
Source

atomics.lisp (file)


Previous: , Up: Exported definitions   [Contents][Index]

5.1.3 Conditions

Condition: implementation-not-supported ()

Error signalled on unsupported implementations.

This error may be signalled when the library is loaded and the current implementation is entirely unsupported, or if the current operation is not supported by the implementation.

See OPERATION

Package

atomics

Source

atomics.lisp (file)

Direct superclasses

error (condition)

Direct methods

operation (method)

Direct slots
Slot: operation
Initargs

:operation

Initform

(quote nil)

Readers

operation (generic function)


Previous: , Up: Definitions   [Contents][Index]

5.2 Internal definitions


Previous: , Up: Internal definitions   [Contents][Index]

5.2.1 Functions

Function: no-support &optional OPERATION
Package

atomics

Source

atomics.lisp (file)


Previous: , Up: Top   [Contents][Index]

Appendix A Indexes


Next: , Previous: , Up: Indexes   [Contents][Index]

A.1 Concepts

Jump to:   A   F   L  
Index Entry  Section

A
atomics.asd: The atomics<dot>asd file
atomics/atomics.lisp: The atomics/atomics<dot>lisp file
atomics/documentation.lisp: The atomics/documentation<dot>lisp file

F
File, Lisp, atomics.asd: The atomics<dot>asd file
File, Lisp, atomics/atomics.lisp: The atomics/atomics<dot>lisp file
File, Lisp, atomics/documentation.lisp: The atomics/documentation<dot>lisp file

L
Lisp File, atomics.asd: The atomics<dot>asd file
Lisp File, atomics/atomics.lisp: The atomics/atomics<dot>lisp file
Lisp File, atomics/documentation.lisp: The atomics/documentation<dot>lisp file

Jump to:   A   F   L  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.2 Functions

Jump to:   A   C   D   F   G   M   N   O  
Index Entry  Section

A
atomic-decf: Exported macros
atomic-incf: Exported macros
atomic-update: Exported macros

C
cas: Exported macros

D
defstruct: Exported macros

F
Function, no-support: Internal functions

G
Generic Function, operation: Exported generic functions

M
Macro, atomic-decf: Exported macros
Macro, atomic-incf: Exported macros
Macro, atomic-update: Exported macros
Macro, cas: Exported macros
Macro, defstruct: Exported macros
Method, operation: Exported generic functions

N
no-support: Internal functions

O
operation: Exported generic functions
operation: Exported generic functions

Jump to:   A   C   D   F   G   M   N   O  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.3 Variables

Jump to:   O   S  
Index Entry  Section

O
operation: Exported conditions

S
Slot, operation: Exported conditions

Jump to:   O   S  

Previous: , Up: Indexes   [Contents][Index]

A.4 Data types

Jump to:   A   C   I   P   S  
Index Entry  Section

A
atomics: The atomics system
atomics: The atomics package

C
Condition, implementation-not-supported: Exported conditions

I
implementation-not-supported: Exported conditions

P
Package, atomics: The atomics package

S
System, atomics: The atomics system

Jump to:   A   C   I   P   S