source: project/wiki/eggref/4/hopefully @ 33010

Last change on this file since 33010 was 33010, checked in by svnwiki, 6 years ago

Anonymous wiki edit for IP [85.177.47.85]: Clarify further.

File size: 5.9 KB
Line 
1[[tags: egg]]
2== hopefully
3
4Simple composable transactional memory.
5
6The API is similar to Clojure and STMX.  However (currently) limited.
7
8[[toc:]]
9=== Overview
10
11This egg provides two modules: {{hopefully}} and
12{{hopefully-current}}.
13
14Module {{hopefully}} contains bindings recommended to use.  These
15transactions are roughly as fast as normal locking.  (Depending more
16on compiler optimizations and usage szenarios.)
17
18Module {{hopefully-current}} adds support for the concept of an
19implicit current transaction, which is nice but and order of magnitude
20more expensive at runtime.
21
22=== Issues
23
24{{define-a-record}} and {{define-ac-record}} both define a
25{{TYPE-FIELD}} accessor, though with incompatible semantics.  While
26the AC-variant is changes meaning depending on whether or not there is
27a {{current-transaction}} on the thread.  The A-variant always returns
28the external value.  The former is OK, since the whole purpose is to
29be downward compatible to define-record based code not aware of
30transactions.  But once most of a code base is converted to use
31references, once only wants to replace {{define-ac-record}} with
32{{define-a-record}}.  At that time those field readers should not
33suddenly change meaning anymore.   The old "global" accessors should
34become inaccessible.  The "alway-return-global-value"
35accessors need to be renamed (and the renamed value defined by {{define-ac-record}} as
36well to aid the transition).  Just how rename it?  Append "{{@}}"?
37
38=== Modules
39
40==== hopefully
41
42<syntax>define-a-record</syntax>
43
44Like define-record, defines procedures according to the following
45pattern.
46
47<procedure>(make-TYPE FIELDS ...) -> AREC</procedure>
48
49<procedure>(TYPE-FIELD-ref AREC TNX) => REF</procedure>
50
51Return a reference for use with CELL-REF (alias "@") and ALTER!.
52
53Note: Try to use this accessor just once per object+field.  Multiple
54calls (within a lightweight transaction) will produce independent
55references.  (If these become inconsistent, the commit will fail
56nevertheless.)  Only those references used to {{(set! (@ REF) val)}}
57will return the in-transaction value.
58
59<procedure>(TYPE-FIELD AREC)</procedure>
60
61Return the FIELD value visible without transactions in effect.
62
63<procedure>(TYPE-tag AREC)</procedure>
64
65Purely for debugging.  Mayb e removed. Return the internal version tag
66of the slot.
67
68<procedure>(cell-ref REF)</procedure>
69
70Retrieve the in-transaction value from the {{REF}}erence (and add it
71to the transactions dependencies).
72
73<procedure>(@ REF)</procedure>
74
75Alias to cell-ref.  With generalized setter.
76
77<procedure>(alter! REF val)</procedure>
78
79Alter a {{REF}}erence (produced by the {{type}}-{{field}}-ref
80accessors to hold the new value {{val}}.  This also adds the cell to
81the dependencies of the transaction associated with the {{REF}}.
82
83<procedure>(call-with-transaction PROC)</procedure>
84<procedure>(call-with-transaction/values PROC)</procedure>
85
86Call PROC with one argument, a fresh (lightweight) transaction.
87PROC may be called multiple times in case of a conflict.
88(See hopefully-current for the difference to heavy transactions).
89
90Returns whatever PROC returns.  Use {{call-with-transaction}} for
91multiple value returns {{call-with-transaction/values}} returns all
92values.
93
94Note: One {{should not}} pass the transaction argument around among
95threads or capture it.  Most (if not all) resulting conditions should
96be handled.  But it is no good idea.
97
98==== hopefully-current
99
100This module introduces the concept of a default
101{{current-transaction}} and heavy transactions.
102
103When a reference is added to a heavy transaction, the transactions
104dependencies are searched and if a reference to the same object+slot
105is found, it is returned.
106
107<syntax>define-ac-record</syntax>
108
109Like {{define-a-record}}.
110
111{{define-ac-record}} is provided for maximum compatibility with
112{{define-record}}.  Just changing the record definition should make
113code aware of the current transaction.
114
115<procedure>(make-TYPE FIELDS..) -> ACREC</procedure>
116
117Accessors:
118
119<procedure>(TYPE-FIELD-ref ACREC TNX) => REF</procedure>
120
121Return a reference to the in-transaction value of {{field}} in
122{{ACREC}} for use with CELL-REF (alias "@") and ALTER!.  See sibling
123definition in {{hopefully}}.
124
125<procedure>(TYPE-FIELD ACREC)</procedure>
126
127Return the value of {{field}} in ACREC.  Returns the in-transaction
128value with respect to the {{current-transaction}} or the outside value
129if there is no {{current-transaction}} in the {{current-thread}}.
130
131Note: this is roughly an order of magnitude slower than the
132corresponding accessor from {{define-a-record}}
133
134<procedure>(TYPE-FIELD-set! ACREC val) -> undefined</procedure>
135
136Set the value of {{field}} to {{val}}.  Changes the in-transaction
137value respect to the {{current-transaction}} or the outside value if
138there is no {{current-transaction}} in the {{current-thread}}.
139
140Note: this is roughly an order of magnitude slower than the
141corresponding accessor from {{define-a-record}}
142
143<procedure>(with-current-transaction THUNK)</procedure>
144
145Establish a new {{current-transaction}} and call {{THUNK}}.
146After thunk completed, commit the current transaction.
147If that failes, THUNK is called again.
148
149Returns whatever THUNK returns.
150
151=== Examples
152
153<enscript highlight="scheme">
154(define-a-record gbox v)
155(define b1 (make-gbox 0))
156(define b2 (make-gbox 1))
157
158(call-with-transaction
159 (lambda (tnx)
160   (let ((x (gbox-v-ref b1 tnx))
161         (i (gbox-v-ref b2 tnx)))
162     (let ((ni (@ i)))
163       (alter! x (+ (@ x) ni))
164       (alter! i (add1 ni))))))
165</enscript>
166
167See also tests/run.scm.
168
169=== Compile time options
170
171-D no-dirty-tagging : save some internal consitency checks
172-D debug: add additional consitency checks
173
174=== About this egg
175
176==== Source
177
178Latest version: [[http://askemos.org/chicken-eggs/hopefully/hopefully.tar.gz|hopefully from askemos.org]]
179
180==== Authors
181
182Jörg F. Wittenberger
183
184==== Version History
185
1860.2.1: 2015-12-19 -- Some tweaks.
187
1880.2: 2015-12-18 -- Replacing chicken hash tables with llrb trees made
189ac-records about 4x faster.
190
1910.1.1: 2015-12-18 -- Fix missing unquote.
192
1930.1: 2015-12-16 -- Initial Release
Note: See TracBrowser for help on using the repository browser.