forked from Shinmera/atomics
/
documentation.lisp
165 lines (126 loc) · 5.91 KB
/
documentation.lisp
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
#|
This file is a part of Atomics
(c) 2019 Shirakumo http://tymoon.eu (shinmera@tymoon.eu)
Author: Nicolas Hafner <shinmera@tymoon.eu>
|#
(in-package #:org.shirakumo.atomics)
(docs:define-docs
(type 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")
(function operation
"Returns the unsupported operation or NIL on entirely unsupported implementations.
See IMPLEMENTATION-NOT-SUPPORTED")
(function cas
"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 Clasp ECL LispWorks SBCL
CAR X X X X X
CDR X X X X X
FIRST X X X
REST X X X
SVREF X X X X X X
SYMBOL-PLIST X X X X
SYMBOL-VALUE X X X X X
SLOT-VALUE X* X X* X* X*
MEMREF X
MEMREF-INT X
struct-slot X X* X X* X X*
special-var X X X X X
custom X 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.
# Clasp (MP:CAS)
- SLOT-VALUE can only be used for :INSTANCE and :CLASS allocated
slots. Methods on SLOT-VALUE-USING-CLASS etc. are ignored. If the
slot is missing, SLOT-MISSING is called with operation = MP:CAS,
and new-value = a list of OLD and NEW. The slot must be bound.
- SYMBOL-VALUE (and a special variable directly) accesses the
dynamically bound value if it is dynamically bound, rather than the
global value.
# 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.")
(function atomic-incf
"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 Clasp ECL LispWorks SBCL
CAR X X X X X X
CDR X X X X X X
FIRST X X X
REST X X X
SVREF X X X X X
AREF 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 X*
special-var X X X X
custom X X X X
global (SBCL) X*
Further restrictions apply:
# Allegro (EXCL:ATOMIC-INCF)
See CAS
# Clasp (MP: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")
(function atomic-decf
"Atomically decreases place by the specified delta.
Returns the value the place has been set to.
For restrictions, see ATOMIC-INCF.
See ATOMIC-INCF")
(function atomic-update
"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")
(function defstruct
"Wrapper around CL:DEFSTRUCT to portably define atomically modifiable structures.
See CL:DEFSTRUCT"))