64
64
<list type="bulleted">
65
65
<item>In the current implementation, every object insert and
66
66
look-up operation results in a copy of the object.</item>
67
<item>This module provides very limited support for concurrent
68
updates. No locking is available, but the <c>safe_fixtable/2</c>
69
function can be used to guarantee that a sequence of
70
<c>first/1</c> and <c>next/2</c> calls will traverse the table
71
without errors and that each object in the table is visited
72
exactly once, even if another process (or the same process)
73
simultaneously deletes or inserts objects into the table.
74
Nothing more is guaranteed; in particular any object inserted
75
during a traversal <em>may</em> be visited in the traversal.
77
67
<item><c>'$end_of_table'</c> should not be used as a key since
78
68
this atom is used to mark the end of the table when using
79
69
<c>first</c>/<c>next</c>.</item>
97
87
table identifier is invalid.</p>
90
<section><marker id="concurrency"></marker>
91
<title>Concurrency</title>
92
<p>This module provides some limited support for concurrent access.
93
All updates to single objects are guaranteed to be both <em>atomic</em>
94
and <em>isolated</em>. This means that an updating operation towards
95
a single object will either succeed or fail completely without any
96
effect at all (atomicy).
97
Nor can any intermediate results of the update be seen by other
98
processes (isolation). Some functions that update several objects
99
state that they even guarantee atomicy and isolation for the entire
100
operation. In database terms the isolation level can be seen as
101
"serializable", as if all isolated operations were carried out serially,
102
one after the other in a strict order.</p>
103
<p>No other support is available within ETS that would guarantee
104
consistency between objects. However, the <c>safe_fixtable/2</c>
105
function can be used to guarantee that a sequence of
106
<c>first/1</c> and <c>next/2</c> calls will traverse the table
107
without errors and that each existing object in the table is visited
108
exactly once, even if another process (or the same process)
109
simultaneously deletes or inserts objects into the table.
110
Nothing more is guaranteed; in particular objects that are inserted
111
or deleted during such a traversal may be visited once or not at all.
112
Functions that internally traverse over a table, like <c>select</c>
113
and <c>match</c>, will give the same guarantee as <c>safe_fixtable</c>.</p>
101
116
<marker id="match_spec"></marker>
102
117
<title>Match Specifications</title>
158
173
<v>Tab = tid() | atom()</v>
161
<p>Delete all objects in the ETS table <c>Tab</c>. The deletion
176
<p>Delete all objects in the ETS table <c>Tab</c>.
177
The operation is guaranteed to be
178
<seealso marker="#concurrency">atomic and isolated</seealso>.</p>
173
189
<p>Delete the exact object <c>Object</c> from the ETS table,
174
190
leaving objects with the same key but other differences
175
(useful for type <c>bag</c>).</p>
191
(useful for type <c>bag</c>). In a <c>duplicate_bag</c>, all
192
instances of the object will be deleted.</p>
564
581
<c>set</c>, one will be inserted, which one is
565
582
not defined. The same thing holds for <c>ordered_set</c>, but
566
583
will also happen if the keys <em>compare equal</em>.</p>
584
<p>The entire operation is guaranteed to be
585
<seealso marker="#concurrency">atomic and isolated</seealso>,
586
even when a list of objects is inserted.</p>
583
603
list, the function checks <em>every</em> key prior to
584
604
inserting anything. Nothing will be inserted if not
585
605
<em>all</em> keys present in the list are absent from the
606
table. Like <c>insert/2</c>, the entire operation is guaranteed to be
607
<seealso marker="#concurrency">atomic and isolated</seealso>.</p>
1024
1045
mutates (writes to) the table will obtain exclusive access,
1025
1046
blocking any concurrent access of the same table until finished.
1026
1047
If set to <c>true</c>, the table is optimized towards concurrent
1027
write access. Different parts of the same table can be mutated
1028
(and read) by concurrent processes. This is achieve to some degree
1048
write access. Different objects of the same table can be mutated
1049
(and read) by concurrent processes. This is achieved to some degree
1029
1050
at the expense of single access and concurrent reader performance.
1030
Table typ <c>ordered_set</c> is not affected by this option in current
1051
Note that this option does not change any guarantees about
1052
<seealso marker="#concurrency">atomicy and isolation</seealso>.
1053
Functions that makes such promises over several objects (like
1054
<c>insert/2</c>) will gain less (or nothing) from this option.</p>
1055
<p>Table type <c>ordered_set</c> is not affected by this option in current
1031
1056
implementation.</p>