1ets(3) Erlang Module Definition ets(3)
2
6 ets - Built-in term storage.
7
9 This module is an interface to the Erlang built-in term storage BIFs.
10 These provide the ability to store very large quantities of data in an
11 Erlang runtime system, and to have constant access time to the data.
12 (In the case of ordered_set, see below, access time is proportional to
13 the logarithm of the number of stored objects.)
14 Data is organized as a set of dynamic tables, which can store tuples.
16 Each table is created by a process. When the process terminates, the
17 table is automatically destroyed. Every table has access rights set at
18 creation.
19 Tables are divided into four different types, set, ordered_set, bag,
21 and duplicate_bag. A set or ordered_set table can only have one object
22 associated with each key. A bag or duplicate_bag table can have many
23 objects associated with each key.
24 Insert and lookup times in tables of type set are constant, regardless
26 of the table size. For table types bag and duplicate_bag time is pro‐
27 portional to the number of objects with the same key. Even seemingly
28 unrelated keys may inflict linear search to be skipped past while look‐
29 ing for the key of interest (due to hash collision).
30 Warning:
32 For tables of type bag and duplicate_bag, avoid inserting an extensive
33 amount of objects with the same key. It will hurt insert and lookup
34 performance as well as real time characteristics of the runtime envi‐
35 ronment (hash bucket linear search do not yield).
36 The ordered_set table type uses a binary search tree. Insert and lookup
39 times are proportional to the logarithm of the number of objects in the
40 table.
41 Note:
43 The number of tables stored at one Erlang node used to be limited. This
44 is no longer the case (except by memory usage). The previous default
45 limit was about 1400 tables and could be increased by setting the envi‐
46 ronment variable ERL_MAX_ETS_TABLES or the command line option +e be‐
47 fore starting the Erlang runtime system. This hard limit has been re‐
48 moved, but it is currently useful to set the ERL_MAX_ETS_TABLES anyway.
49 It should be set to an approximate of the maximum amount of tables used
50 since an internal table for named tables is sized using this value. If
51 large amounts of named tables are used and ERL_MAX_ETS_TABLES hasn't
52 been increased, the performance of named table lookup will degrade.
53 Notice that there is no automatic garbage collection for tables. Even
56 if there are no references to a table from any process, it is not auto‐
57 matically destroyed unless the owner process terminates. To destroy a
58 table explicitly, use function delete/1. The default owner is the
59 process that created the table. To transfer table ownership at process
60 termination, use option heir or call give_away/3.
61 Some implementation details:
63 * In the current implementation, every object insert and look-up op‐
65 eration results in a copy of the object.
66 * '$end_of_table' is not to be used as a key, as this atom is used to
68 mark the end of the table when using functions first/1 and next/2.
69 Notice the subtle difference between matching and comparing equal,
71 which is demonstrated by table types set and ordered_set:
72 * Two Erlang terms match if they are of the same type and have the
74 same value, so that 1 matches 1, but not 1.0 (as 1.0 is a float()
75 and not an integer()).
76 * Two Erlang terms compare equal if they either are of the same type
78 and value, or if both are numeric types and extend to the same
79 value, so that 1 compares equal to both 1 and 1.0.
80 * The ordered_set works on the Erlang term order and no defined order
82 exists between an integer() and a float() that extends to the same
83 value. Hence the key 1 and the key 1.0 are regarded as equal in an
84 ordered_set table.
85
87 Functions in this module fail by raising an error exception with error
88 reason:
89 badarg:
91 If any argument has the wrong format.
92 badarg:
94 If the table identifier is invalid.
95 badarg:
97 If the operation is denied because of table access rights (pro‐
98 tected or private).
99 system_limit:
101 Modification of a value causes it to not be representable inter‐
102 nally in the VM. For example, incrementation of a counter past the
103 largest integer representable.
104 system_limit:
106 If a match specification passed as argument has excessive nesting
107 which causes scheduler stack exhaustion for the scheduler that the
108 calling process is executing on. Scheduler stack size can be con‐
109 figured when starting the runtime system.
110
112 This module provides some limited support for concurrent access. All
113 updates to single objects are guaranteed to be both atomic and iso‐
114 lated. This means that an updating operation to a single object either
115 succeeds or fails completely without any effect (atomicity) and that no
116 intermediate results of the update can be seen by other processes (iso‐
117 lation). Some functions that update many objects state that they even
118 guarantee atomicity and isolation for the entire operation. In database
119 terms the isolation level can be seen as "serializable", as if all iso‐
120 lated operations are carried out serially, one after the other in a
121 strict order.
122
124 There are different ways to traverse through the objects of a table.
125 * Single-step traversal one key at at time, using first/1, next/2,
127 last/1 and prev/2.
128 * Search with simple match patterns, using match/1/2/3,
130 match_delete/2 and match_object/1/2/3.
131 * Search with more powerful match specifications, using select/1/2/3,
133 select_count/2, select_delete/2, select_replace/2 and select_re‐
134 verse/1/2/3.
135 * Table conversions, using tab2file/2/3 and tab2list/1.
137 No table traversal will guarantee a consistent snapshot of the entire
139 table if the table is also updated by concurrent processes during the
140 traversal. The result of each concurrently updated object may be seen
141 (or not) depending on if it has happened when the traversal visits that
142 part of the table. The only way to guarantee a full consistent table
143 snapshot (if you really need that) is to disallow concurrent updates
144 during the entire traversal.
145 Moreover, traversals not done in a safe way, on tables where keys are
147 inserted or deleted during the traversal, may yield the following unde‐
148 sired effects:
149 * Any key may be missed.
151 * Any key may be found more than once.
153 * The traversal may fail with badarg exception if keys are deleted.
155 A table traversal is safe if either
157 * the table is of type ordered_set.
159 * the entire table traversal is done within one ETS function call.
161 * function safe_fixtable/2 is used to keep the table fixated during
163 the entire traversal.
164 Note:
166 Even though the access of a single object is always guaranteed to be
167 atomic and isolated, each traversal through a table to find the next
168 key is not done with such guarantees. This is often not a problem, but
169 may cause rare subtle "unexpected" effects if a concurrent process in‐
170 serts objects during a traversal. For example, consider one process do‐
171 ing
172 ets:new(t, [ordered_set, named_table]),
174 ets:insert(t, {1}),
175 ets:insert(t, {2}),
176 ets:insert(t, {3}),
177 A concurrent call to ets:first(t), done by another process, may then in
180 rare cases return 2 even though 2 has never existed in the table or‐
181 dered as the first key. In the same way, a concurrent call to
182 ets:next(t, 1) may return 3 even though 3 never existed in the table
183 ordered directly after 1.
184 Effects like this are improbable but possible. The probability will
186 further be reduced (if not vanish) if table option write_concurrency is
187 not enabled. This can also only be a potential concern for ordered_set
188 where the traversal order is defined.
189 Traversals using match and select functions may not need to scan the
192 entire table depending on how the key is specified. A match pattern
193 with a fully bound key (without any match variables) will optimize the
194 operation to a single key lookup without any table traversal at all.
195 For ordered_set a partially bound key will limit the traversal to only
196 scan a subset of the table based on term order. A partially bound key
197 is either a list or a tuple with a prefix that is fully bound. Example:
198 1> T = ets:new(t,[ordered_set]), ets:insert(T, {"555-1234", "John Smith"}).
200 true
201 2> %% Efficient search of all with area code 555
202 2> ets:match(T,{[$5,$5,$5,$- |'$1'],'$2'}).
203 [["1234","John Smith"]]
204
207 Some of the functions use a match specification, match_spec. For a
208 brief explanation, see select/2. For a detailed description, see sec‐
209 tion Match Specifications in Erlang in ERTS User's Guide.
210 A match specifications with excessive nesting will cause a system_limit
212 error exception to be raised.
213
215 table_access() = public | protected | private
216 continuation()
218 Opaque continuation used by select/1,3, select_reverse/1,3,
220 match/1,3, and match_object/1,3.
221 match_spec() = [{match_pattern(), [term()], [term()]}]
223 A match specification, see Match Specifications.
225 compiled_match_spec()
227 A compiled match specification.
229 match_pattern() = atom() | tuple()
231 table() = atom() | tid()
233 tid()
235 A table identifier, as returned by new/2.
237 table_type() = set | ordered_set | bag | duplicate_bag
239
241 all() -> [Table]
242 Types:
244 Table = table()
246 Returns a list of all tables at the node. Named tables are spec‐
248 ified by their names, unnamed tables are specified by their ta‐
249 ble identifiers.
250 There is no guarantee of consistency in the returned list. Ta‐
252 bles created or deleted by other processes "during" the
253 ets:all() call either are or are not included in the list. Only
254 tables created/deleted before ets:all() is called are guaranteed
255 to be included/excluded.
256 delete(Table) -> true
258 Types:
260 Table = table()
262 Deletes the entire table Table.
264 delete(Table, Key) -> true
266 Types:
268 Table = table()
270 Key = term()
271 Deletes all objects with key Key from table Table. This function
273 succeeds even if no objects with key Key exist.
274 delete_all_objects(Table) -> true
276 Types:
278 Table = table()
280 Delete all objects in the ETS table Table. The operation is
282 guaranteed to be atomic and isolated.
283 delete_object(Table, Object) -> true
285 Types:
287 Table = table()
289 Object = tuple()
290 Delete the exact object Object from the ETS table, leaving ob‐
292 jects with the same key but other differences (useful for type
293 bag). In a duplicate_bag table, all instances of the object are
294 deleted.
295 file2tab(Filename) -> {ok, Table} | {error, Reason}
297 Types:
299 Filename = file:name()
301 Table = table()
302 Reason = term()
303 Reads a file produced by tab2file/2 or tab2file/3 and creates
305 the corresponding table Table.
306 Equivalent to file2tab(Filename, []).
308 file2tab(Filename, Options) -> {ok, Table} | {error, Reason}
310 Types:
312 Filename = file:name()
314 Table = table()
315 Options = [Option]
316 Option = {verify, boolean()}
317 Reason = term()
318 Reads a file produced by tab2file/2 or tab2file/3 and creates
320 the corresponding table Table.
321 The only supported option is {verify,boolean()}. If verification
323 is turned on (by specifying {verify,true}), the function uses
324 whatever information is present in the file to assert that the
325 information is not damaged. How this is done depends on which
326 extended_info was written using tab2file/3.
327 If no extended_info is present in the file and {verify,true} is
329 specified, the number of objects written is compared to the size
330 of the original table when the dump was started. This can make
331 verification fail if the table was public and objects were added
332 or removed while the table was dumped to file. To avoid this
333 problem, either do not verify files dumped while updated simul‐
334 taneously or use option {extended_info, [object_count]} to
335 tab2file/3, which extends the information in the file with the
336 number of objects written.
337 If verification is turned on and the file was written with op‐
339 tion {extended_info, [md5sum]}, reading the file is slower and
340 consumes radically more CPU time than otherwise.
341 {verify,false} is the default.
343 first(Table) -> Key | '$end_of_table'
345 Types:
347 Table = table()
349 Key = term()
350 Returns the first key Key in table Table. For an ordered_set ta‐
352 ble, the first key in Erlang term order is returned. For other
353 table types, the first key according to the internal order of
354 the table is returned. If the table is empty, '$end_of_table' is
355 returned.
356 To find subsequent keys in the table, use next/2.
358 foldl(Function, Acc0, Table) -> Acc1
360 Types:
362 Function = fun((Element :: term(), AccIn) -> AccOut)
364 Table = table()
365 Acc0 = Acc1 = AccIn = AccOut = term()
366 Acc0 is returned if the table is empty. This function is similar
368 to lists:foldl/3. The table elements are traversed in an unspec‐
369 ified order, except for ordered_set tables, where they are tra‐
370 versed first to last.
371 If Function inserts objects into the table, or another process
373 inserts objects into the table, those objects can (depending on
374 key ordering) be included in the traversal.
375 foldr(Function, Acc0, Table) -> Acc1
377 Types:
379 Function = fun((Element :: term(), AccIn) -> AccOut)
381 Table = table()
382 Acc0 = Acc1 = AccIn = AccOut = term()
383 Acc0 is returned if the table is empty. This function is similar
385 to lists:foldr/3. The table elements are traversed in an unspec‐
386 ified order, except for ordered_set tables, where they are tra‐
387 versed last to first.
388 If Function inserts objects into the table, or another process
390 inserts objects into the table, those objects can (depending on
391 key ordering) be included in the traversal.
392 from_dets(Table, DetsTab) -> true
394 Types:
396 Table = table()
398 DetsTab = dets:tab_name()
399 Fills an already created ETS table with the objects in the al‐
401 ready opened Dets table DetsTab. Existing objects in the ETS ta‐
402 ble are kept unless overwritten.
403 If any of the tables does not exist or the Dets table is not
405 open, a badarg exception is raised.
406 fun2ms(LiteralFun) -> MatchSpec
408 Types:
410 LiteralFun = function()
412 MatchSpec = match_spec()
413 Pseudo function that by a parse_transform translates LiteralFun
415 typed as parameter in the function call to a match specifica‐
416 tion. With "literal" is meant that the fun must textually be
417 written as the parameter of the function, it cannot be held in a
418 variable that in turn is passed to the function.
419 The parse transform is provided in the ms_transform module and
421 the source must include file ms_transform.hrl in STDLIB for this
422 pseudo function to work. Failing to include the hrl file in the
423 source results in a runtime error, not a compile time error. The
424 include file is easiest included by adding line -in‐
425 clude_lib("stdlib/include/ms_transform.hrl"). to the source
426 file.
427 The fun is very restricted, it can take only a single parameter
429 (the object to match): a sole variable or a tuple. It must use
430 the is_ guard tests. Language constructs that have no represen‐
431 tation in a match specification (if, case, receive, and so on)
432 are not allowed.
433 The return value is the resulting match specification.
435 Example:
437 1> ets:fun2ms(fun({M,N}) when N > 3 -> M end).
439 [{{'$1','$2'},[{'>','$2',3}],['$1']}]
440 Variables from the environment can be imported, so that the fol‐
442 lowing works:
443 2> X=3.
445 3
446 3> ets:fun2ms(fun({M,N}) when N > X -> M end).
447 [{{'$1','$2'},[{'>','$2',{const,3}}],['$1']}]
448 The imported variables are replaced by match specification const
450 expressions, which is consistent with the static scoping for Er‐
451 lang funs. However, local or global function calls cannot be in
452 the guard or body of the fun. Calls to built-in match specifica‐
453 tion functions is of course allowed:
454 4> ets:fun2ms(fun({M,N}) when N > X, my_fun(M) -> M end).
456 Error: fun containing local Erlang function calls
457 ('my_fun' called in guard) cannot be translated into match_spec
458 {error,transform_error}
459 5> ets:fun2ms(fun({M,N}) when N > X, is_atom(M) -> M end).
460 [{{'$1','$2'},[{'>','$2',{const,3}},{is_atom,'$1'}],['$1']}]
461 As shown by the example, the function can be called from the
463 shell also. The fun must be literally in the call when used from
464 the shell as well.
465 Warning:
467 If the parse_transform is not applied to a module that calls
468 this pseudo function, the call fails in runtime (with a badarg).
469 The ets module exports a function with this name, but it is
470 never to be called except when using the function in the shell.
471 If the parse_transform is properly applied by including header
472 file ms_transform.hrl, compiled code never calls the function,
473 but the function call is replaced by a literal match specifica‐
474 tion.
475 For more information, see ms_transform(3).
478 give_away(Table, Pid, GiftData) -> true
480 Types:
482 Table = table()
484 Pid = pid()
485 GiftData = term()
486 Make process Pid the new owner of table Table. If successful,
488 message {'ETS-TRANSFER',Table,FromPid,GiftData} is sent to the
489 new owner.
490 The process Pid must be alive, local, and not already the owner
492 of the table. The calling process must be the table owner.
493 Notice that this function does not affect option heir of the ta‐
495 ble. A table owner can, for example, set heir to itself, give
496 the table away, and then get it back if the receiver terminates.
497 i() -> ok
499 Displays information about all ETS tables on a terminal.
501 i(Table) -> ok
503 Types:
505 Table = table()
507 Browses table Table on a terminal.
509 info(Table) -> InfoList | undefined
511 Types:
513 Table = table()
515 InfoList = [InfoTuple]
516 InfoTuple =
517 {compressed, boolean()} |
518 {decentralized_counters, boolean()} |
519 {heir, pid() | none} |
520 {id, tid()} |
521 {keypos, integer() >= 1} |
522 {memory, integer() >= 0} |
523 {name, atom()} |
524 {named_table, boolean()} |
525 {node, node()} |
526 {owner, pid()} |
527 {protection, table_access()} |
528 {size, integer() >= 0} |
529 {type, table_type()} |
530 {write_concurrency, boolean()} |
531 {read_concurrency, boolean()}
532 Returns information about table Table as a list of tuples. If
534 Table has the correct type for a table identifier, but does not
535 refer to an existing ETS table, undefined is returned. If Table
536 is not of the correct type, a badarg exception is raised.
537 {compressed, boolean()}:
539 Indicates if the table is compressed.
540 {decentralized_counters, boolean()}:
542 Indicates whether the table uses decentralized_counters.
543 {heir, pid() | none}:
545 The pid of the heir of the table, or none if no heir is set.
546 {id,tid()}:
548 The table identifier.
549 {keypos, integer() >= 1}:
551 The key position.
552 {memory, integer() >= 0}:
554 The number of words allocated to the table.
555 {name, atom()}:
557 The table name.
558 {named_table, boolean()}:
560 Indicates if the table is named.
561 {node, node()}:
563 The node where the table is stored. This field is no longer
564 meaningful, as tables cannot be accessed from other nodes.
565 {owner, pid()}:
567 The pid of the owner of the table.
568 {protection,access()}:
570 The table access rights.
571 {size, integer() >= 0}:
573 The number of objects inserted in the table.
574 {type,type()}:
576 The table type.
577 {read_concurrency, boolean()}:
579 Indicates whether the table uses read_concurrency or not.
580 {write_concurrency, WriteConcurrencyAlternative}:
582 Indicates which write_concurrency option the table uses.
583 Note:
585 The execution time of this function is affected by the decen‐
586 tralized_counters table option. The execution time is much
587 longer when the decentralized_counters option is set to true
588 than when the decentralized_counters option is set to false.
589 info(Table, Item) -> Value | undefined
592 Types:
594 Table = table()
596 Item =
597 binary | compressed | decentralized_counters | fixed |
598 heir |
599 id | keypos | memory | name | named_table | node | owner
600 |
601 protection | safe_fixed | safe_fixed_monotonic_time |
602 size |
603 stats | type | write_concurrency | read_concurrency
604 Value = term()
605 Returns the information associated with Item for table Table, or
607 returns undefined if Table does not refer an existing ETS table.
608 If Table is not of the correct type, or if Item is not one of
609 the allowed values, a badarg exception is raised.
610 In addition to the {Item,Value} pairs defined for info/1, the
612 following items are allowed:
613 * Item=binary, Value=BinInfo
615 BinInfo is a list containing miscellaneous information about
617 binaries kept by the table. This Item can be changed or re‐
618 moved without prior notice. In the current implementation
619 BinInfo is a list of tuples {BinaryId,BinarySize,BinaryRefc‐
620 Count}.
621 * Item=fixed, Value=boolean()
623 Indicates if the table is fixed by any process.
625 *
627 Item=safe_fixed|safe_fixed_monotonic_time, Value={Fixation‐
630 Time,Info}|false
631 If the table is fixed using safe_fixtable/2, the call re‐
633 turns a tuple where FixationTime is the last time when the
634 table changed from unfixed to fixed.
635 The format and value of FixationTime depends on Item:
637 safe_fixed:
639 FixationTime corresponds to the result returned by er‐
640 lang:timestamp/0 at the time of fixation. Notice that when
641 the system uses single or multi time warp modes this can
642 produce strange results, as the use of safe_fixed is not
643 time warp safe. Time warp safe code must use
644 safe_fixed_monotonic_time instead.
645 safe_fixed_monotonic_time:
647 FixationTime corresponds to the result returned by er‐
648 lang:monotonic_time/0 at the time of fixation. The use of
649 safe_fixed_monotonic_time is time warp safe.
650 Info is a possibly empty lists of tuples {Pid,RefCount}, one
652 tuple for every process the table is fixed by now. RefCount
653 is the value of the reference counter and it keeps track of
654 how many times the table has been fixed by the process.
655 Table fixations are not limited to safe_fixtable/2. Tempo‐
657 rary fixations may also be done by for example traversing
658 functions like select and match. Such table fixations are
659 automatically released before the corresponding functions
660 returns, but they may be seen by a concurrent call to
661 ets:info(T,safe_fixed|safe_fixed_monotonic_time).
662 If the table is not fixed at all, the call returns false.
664 * Item=stats, Value=tuple()
666 Returns internal statistics about tables on an internal for‐
668 mat used by OTP test suites. Not for production use.
669 Note:
671 The execution time of this function is affected by the decen‐
672 tralized_counters table option when the second argument of the
673 function is size or memory. The execution time is much longer
674 when the decentralized_counters option is set to true than when
675 the decentralized_counters option is set to false.
676 init_table(Table, InitFun) -> true
679 Types:
681 Table = table()
683 InitFun = fun((Arg) -> Res)
684 Arg = read | close
685 Res = end_of_input | {Objects :: [term()], InitFun} | term()
686 Replaces the existing objects of table Table with objects cre‐
688 ated by calling the input function InitFun, see below. This
689 function is provided for compatibility with the dets module, it
690 is not more efficient than filling a table by using insert/2.
691 When called with argument read, the function InitFun is assumed
693 to return end_of_input when there is no more input, or {Objects,
694 Fun}, where Objects is a list of objects and Fun is a new input
695 function. Any other value Value is returned as an error {error,
696 {init_fun, Value}}. Each input function is called exactly once,
697 and if an error occur, the last function is called with argument
698 close, the reply of which is ignored.
699 If the table type is set and more than one object exists with a
701 given key, one of the objects is chosen. This is not necessarily
702 the last object with the given key in the sequence of objects
703 returned by the input functions. This holds also for duplicated
704 objects stored in tables of type bag.
705 insert(Table, ObjectOrObjects) -> true
707 Types:
709 Table = table()
711 ObjectOrObjects = tuple() | [tuple()]
712 Inserts the object or all of the objects in list ObjectOrObjects
714 into table Table.
715 * If the table type is set and the key of the inserted objects
717 matches the key of any object in the table, the old object
718 is replaced.
719 * If the table type is ordered_set and the key of the inserted
721 object compares equal to the key of any object in the table,
722 the old object is replaced.
723 * If the table type is bag and the object matches any whole
725 object in the table, the object is not inserted.
726 * If the list contains more than one object with matching keys
728 and the table type is set, one is inserted, which one is not
729 defined. The same holds for table type ordered_set if the
730 keys compare equal.
731 The entire operation is guaranteed to be atomic and isolated,
733 even when a list of objects is inserted.
734 For bag and duplicate_bag, objects in the list with identical
736 keys will be inserted in list order (from head to tail). That
737 is, a subsequent call to lookup(T,Key) will return them in that
738 inserted order.
739 Note:
741 For bag the insertion order of indentical keys described above
742 was accidentally reverted in OTP 23.0 and later fixed in OTP
743 25.3. That is, from OTP 23.0 up until OTP 25.3 the objects in a
744 list are inserted in reverse order (from tail to head).
745 For duplicate_bag the same faulty reverse insertion exist from
747 OTP 23.0 until OTP 25.3. However, it is unpredictable and may or
748 may not happen. A longer list will increase the probabiliy of
749 the insertion being done in reverse.
750 insert_new(Table, ObjectOrObjects) -> boolean()
753 Types:
755 Table = table()
757 ObjectOrObjects = tuple() | [tuple()]
758 Same as insert/2 except that instead of overwriting objects with
760 the same key (for set or ordered_set) or adding more objects
761 with keys already existing in the table (for bag and dupli‐
762 cate_bag), false is returned.
763 If ObjectOrObjects is a list, the function checks every key be‐
765 fore inserting anything. Nothing is inserted unless all keys
766 present in the list are absent from the table. Like insert/2,
767 the entire operation is guaranteed to be atomic and isolated.
768 is_compiled_ms(Term) -> boolean()
770 Types:
772 Term = term()
774 Checks if a term represent a valid compiled match specification.
776 A compiled match specification is only valid on the Erlang node
777 where it was compiled by calling match_spec_compile/1.
778 Note:
780 Before STDLIB 3.4 (OTP 20.0) compiled match specifications did
781 not have an external representation. If passed through bi‐
782 nary_to_term(term_to_binary(CMS)) or sent to another node and
783 back, the result was always an empty binary <<>>.
784 After STDLIB 3.4 (OTP 20.0) compiled match specifications have
786 an external representation as a node specific reference to the
787 original compiled match specification. If passed through bi‐
788 nary_to_term(term_to_binary(CMS)) or sent to another node and
789 back, the result may or may not be a valid compiled match speci‐
790 fication depending on if the original compiled match specifica‐
791 tion was still alive.
792 last(Table) -> Key | '$end_of_table'
795 Types:
797 Table = table()
799 Key = term()
800 Returns the last key Key according to Erlang term order in table
802 Table of type ordered_set. For other table types, the function
803 is synonymous to first/1. If the table is empty, '$end_of_table'
804 is returned.
805 To find preceding keys in the table, use prev/2.
807 lookup(Table, Key) -> [Object]
809 Types:
811 Table = table()
813 Key = term()
814 Object = tuple()
815 Returns a list of all objects with key Key in table Table.
817 * For tables of type set, bag, or duplicate_bag, an object is
819 returned only if the specified key matches the key of the
820 object in the table.
821 * For tables of type ordered_set, an object is returned if the
823 specified key compares equal to the key of an object in the
824 table.
825 The difference is the same as between =:= and ==.
827 As an example, one can insert an object with integer() 1 as a
829 key in an ordered_set and get the object returned as a result of
830 doing a lookup/2 with float() 1.0 as the key to search for.
831 For tables of type set or ordered_set, the function returns ei‐
833 ther the empty list or a list with one element, as there cannot
834 be more than one object with the same key. For tables of type
835 bag or duplicate_bag, the function returns a list of arbitrary
836 length.
837 Notice that the sequential order of object insertions is pre‐
839 served; the first object inserted with the specified key is the
840 first in the resulting list, and so on. See also the note about
841 list insertion order.
842 lookup_element(Table, Key, Pos) -> Elem
844 Types:
846 Table = table()
848 Key = term()
849 Pos = integer() >= 1
850 Elem = term() | [term()]
851 For a table Table of type set or ordered_set, the function re‐
853 turns the Pos:th element of the object with key Key.
854 For tables of type bag or duplicate_bag, the functions returns a
856 list with the Pos:th element of every object with key Key.
857 If no object with key Key exists, the function exits with reason
859 badarg.
860 If Pos is larger than the size of the tuple, the function exits
862 with reason badarg.
863 The difference between set, bag, and duplicate_bag on one hand,
865 and ordered_set on the other, regarding the fact that or‐
866 dered_set view keys as equal when they compare equal whereas the
867 other table types regard them equal only when they match, holds
868 for lookup_element/3.
869 lookup_element(Table, Key, Pos, Default) -> Elem
871 Types:
873 Table = table()
875 Key = term()
876 Pos = integer() >= 1
877 Default = term()
878 Elem = term() | [term()]
879 For a table Table of type set or ordered_set, the function re‐
881 turns the Pos:th element of the object with key Key.
882 For tables of type bag or duplicate_bag, the functions returns a
884 list with the Pos:th element of every object with key Key.
885 If no object with key Key exists, the function returns Default.
887 If Pos is larger than the size of any tuple with a matching key,
889 the function exits with reason badarg.
890 The difference between set, bag, and duplicate_bag on one hand,
892 and ordered_set on the other, regarding the fact that or‐
893 dered_set view keys as equal when they compare equal whereas the
894 other table types regard them equal only when they match, holds
895 for lookup_element/4.
896 match(Continuation) -> {[Match], Continuation} | '$end_of_table'
898 Types:
900 Match = [term()]
902 Continuation = continuation()
903 Continues a match started with match/3. The next chunk of the
905 size specified in the initial match/3 call is returned together
906 with a new Continuation, which can be used in subsequent calls
907 to this function.
908 When there are no more objects in the table, '$end_of_table' is
910 returned.
911 match(Table, Pattern) -> [Match]
913 Types:
915 Table = table()
917 Pattern = match_pattern()
918 Match = [term()]
919 Matches the objects in table Table against pattern Pattern.
921 A pattern is a term that can contain:
923 * Bound parts (Erlang terms)
925 * '_' that matches any Erlang term
927 * Pattern variables '$N', where N=0,1,...
929 The function returns a list with one element for each matching
931 object, where each element is an ordered list of pattern vari‐
932 able bindings, for example:
933 6> ets:match(T, '$1'). % Matches every object in table
935 [[{rufsen,dog,7}],[{brunte,horse,5}],[{ludde,dog,5}]]
936 7> ets:match(T, {'_',dog,'$1'}).
937 [[7],[5]]
938 8> ets:match(T, {'_',cow,'$1'}).
939 []
940 If the key is specified in the pattern, the match is very effi‐
942 cient. If the key is not specified, that is, if it is a variable
943 or an underscore, the entire table must be searched. The search
944 time can be substantial if the table is very large.
945 For tables of type ordered_set, the result is in the same order
947 as in a first/next traversal.
948 match(Table, Pattern, Limit) ->
950 {[Match], Continuation} | '$end_of_table'
951 Types:
953 Table = table()
955 Pattern = match_pattern()
956 Limit = integer() >= 1
957 Match = [term()]
958 Continuation = continuation()
959 Works like match/2, but returns only a limited (Limit) number of
961 matching objects. Term Continuation can then be used in subse‐
962 quent calls to match/1 to get the next chunk of matching ob‐
963 jects. This is a space-efficient way to work on objects in a ta‐
964 ble, which is faster than traversing the table object by object
965 using first/1 and next/2.
966 If the table is empty, '$end_of_table' is returned.
968 Use safe_fixtable/2 to guarantee safe traversal for subsequent
970 calls to match/1.
971 match_delete(Table, Pattern) -> true
973 Types:
975 Table = table()
977 Pattern = match_pattern()
978 Deletes all objects that match pattern Pattern from table Table.
980 For a description of patterns, see match/2.
981 match_object(Continuation) ->
983 {[Object], Continuation} | '$end_of_table'
984 Types:
986 Object = tuple()
988 Continuation = continuation()
989 Continues a match started with match_object/3. The next chunk of
991 the size specified in the initial match_object/3 call is re‐
992 turned together with a new Continuation, which can be used in
993 subsequent calls to this function.
994 When there are no more objects in the table, '$end_of_table' is
996 returned.
997 match_object(Table, Pattern) -> [Object]
999 Types:
1001 Table = table()
1003 Pattern = match_pattern()
1004 Object = tuple()
1005 Matches the objects in table Table against pattern Pattern. For
1007 a description of patterns, see match/2. The function returns a
1008 list of all objects that match the pattern.
1009 If the key is specified in the pattern, the match is very effi‐
1011 cient. If the key is not specified, that is, if it is a variable
1012 or an underscore, the entire table must be searched. The search
1013 time can be substantial if the table is very large.
1014 For tables of type ordered_set, the result is in the same order
1016 as in a first/next traversal.
1017 match_object(Table, Pattern, Limit) ->
1019 {[Object], Continuation} | '$end_of_table'
1020 Types:
1022 Table = table()
1024 Pattern = match_pattern()
1025 Limit = integer() >= 1
1026 Object = tuple()
1027 Continuation = continuation()
1028 Works like match_object/2, but only returns a limited (Limit)
1030 number of matching objects. Term Continuation can then be used
1031 in subsequent calls to match_object/1 to get the next chunk of
1032 matching objects. This is a space-efficient way to work on ob‐
1033 jects in a table, which is faster than traversing the table ob‐
1034 ject by object using first/1 and next/2.
1035 If the table is empty, '$end_of_table' is returned.
1037 Use safe_fixtable/2 to guarantee safe traversal for subsequent
1039 calls to match_object/1.
1040 match_spec_compile(MatchSpec) -> CompiledMatchSpec
1042 Types:
1044 MatchSpec = match_spec()
1046 CompiledMatchSpec = compiled_match_spec()
1047 Transforms a match specification into an internal representation
1049 that can be used in subsequent calls to match_spec_run/2. The
1050 internal representation is opaque. To check the validity of a
1051 compiled match specification, use is_compiled_ms/1.
1052 If term MatchSpec does not represent a valid match specifica‐
1054 tion, a badarg exception is raised.
1055 Note:
1057 This function has limited use in normal code. It is used by the
1058 dets module to perform the dets:select() operations.
1059 match_spec_run(List, CompiledMatchSpec) -> list()
1062 Types:
1064 List = [term()]
1066 CompiledMatchSpec = compiled_match_spec()
1067 Executes the matching specified in a compiled match specifica‐
1069 tion on a list of terms. Term CompiledMatchSpec is to be the re‐
1070 sult of a call to match_spec_compile/1 and is hence the internal
1071 representation of the match specification one wants to use.
1072 The matching is executed on each element in List and the func‐
1074 tion returns a list containing all results. If an element in
1075 List does not match, nothing is returned for that element. The
1076 length of the result list is therefore equal or less than the
1077 length of parameter List.
1078 Example:
1080 The following two calls give the same result (but certainly not
1082 the same execution time):
1083 Table = ets:new...
1085 MatchSpec = ...
1086 % The following call...
1087 ets:match_spec_run(ets:tab2list(Table),
1088 ets:match_spec_compile(MatchSpec)),
1089 % ...gives the same result as the more common (and more efficient)
1090 ets:select(Table, MatchSpec),
1091 Note:
1093 This function has limited use in normal code. It is used by the
1094 dets module to perform the dets:select() operations and by Mne‐
1095 sia during transactions.
1096 member(Table, Key) -> boolean()
1099 Types:
1101 Table = table()
1103 Key = term()
1104 Works like lookup/2, but does not return the objects. Returns
1106 true if one or more elements in the table has key Key, otherwise
1107 false.
1108 new(Name, Options) -> table()
1110 Types:
1112 Name = atom()
1114 Options = [Option]
1115 Option =
1116 Type | Access | named_table |
1117 {keypos, Pos} |
1118 {heir, Pid :: pid(), HeirData} |
1119 {heir, none} |
1120 Tweaks
1121 Type = table_type()
1122 Access = table_access()
1123 WriteConcurrencyAlternative = boolean() | auto
1124 Tweaks =
1125 {write_concurrency, WriteConcurrencyAlternative} |
1126 {read_concurrency, boolean()} |
1127 {decentralized_counters, boolean()} |
1128 compressed
1129 Pos = integer() >= 1
1130 HeirData = term()
1131 Creates a new table and returns a table identifier that can be
1133 used in subsequent operations. The table identifier can be sent
1134 to other processes so that a table can be shared between differ‐
1135 ent processes within a node.
1136 Parameter Options is a list of options that specifies table
1138 type, access rights, key position, and whether the table is
1139 named. Default values are used for omitted options. This means
1140 that not specifying any options ([]) is the same as specifying
1141 [set, protected, {keypos,1}, {heir,none}, {write_concur‐
1142 rency,false}, {read_concurrency,false}, {decentralized_coun‐
1143 ters,false}].
1144 set:
1146 The table is a set table: one key, one object, no order
1147 among objects. This is the default table type.
1148 ordered_set:
1150 The table is a ordered_set table: one key, one object, or‐
1151 dered in Erlang term order, which is the order implied by
1152 the < and > operators. Tables of this type have a somewhat
1153 different behavior in some situations than tables of other
1154 types. Most notably, the ordered_set tables regard keys as
1155 equal when they compare equal, not only when they match.
1156 This means that to an ordered_set table, integer() 1 and
1157 float() 1.0 are regarded as equal. This also means that the
1158 key used to lookup an element does not necessarily match the
1159 key in the returned elements, if float()'s and integer()'s
1160 are mixed in keys of a table.
1161 bag:
1163 The table is a bag table, which can have many objects, but
1164 only one instance of each object, per key.
1165 duplicate_bag:
1167 The table is a duplicate_bag table, which can have many ob‐
1168 jects, including multiple copies of the same object, per
1169 key.
1170 public:
1172 Any process can read or write to the table.
1173 protected:
1175 The owner process can read and write to the table. Other
1176 processes can only read the table. This is the default set‐
1177 ting for the access rights.
1178 private:
1180 Only the owner process can read or write to the table.
1181 named_table:
1183 If this option is present, the table is registered under its
1184 Name which can then be used instead of the table identifier
1185 in subsequent operations.
1186 The function will also return the Name instead of the table
1188 identifier. To get the table identifier of a named table,
1189 use whereis/1.
1190 {keypos,Pos}:
1192 Specifies which element in the stored tuples to use as key.
1193 By default, it is the first element, that is, Pos=1. How‐
1194 ever, this is not always appropriate. In particular, we do
1195 not want the first element to be the key if we want to store
1196 Erlang records in a table.
1197 Notice that any tuple stored in the table must have at least
1199 Pos number of elements.
1200 {heir,Pid,HeirData} | {heir,none}:
1202 Set a process as heir. The heir inherits the table if the
1203 owner terminates. Message {'ETS-TRANS‐
1204 FER',tid(),FromPid,HeirData} is sent to the heir when that
1205 occurs. The heir must be a local process. Default heir is
1206 none, which destroys the table when the owner terminates.
1207 {write_concurrency,WriteConcurrencyAlternative}:
1209 Performance tuning. Defaults to false, in which case an op‐
1210 eration that mutates (writes to) the table obtains exclusive
1211 access, blocking any concurrent access of the same table un‐
1212 til finished. If set to true, the table is optimized for
1213 concurrent write access. Different objects of the same table
1214 can be mutated (and read) by concurrent processes. This is
1215 achieved to some degree at the expense of memory consumption
1216 and the performance of sequential access and concurrent
1217 reading.
1218 The auto alternative for the write_concurrency option is
1220 similar to the true option but automatically adjusts the
1221 synchronization granularity during runtime depending on how
1222 the table is used. This is the recommended write_concurrency
1223 option when using Erlang/OTP 25 and above as it performs
1224 well in most scenarios.
1225 The write_concurrency option can be combined with the op‐
1227 tions read_concurrency and decentralized_counters. You typi‐
1228 cally want to combine write_concurrency with read_concur‐
1229 rency when large concurrent read bursts and large concurrent
1230 write bursts are common; for more information, see option
1231 read_concurrency. It is almost always a good idea to combine
1232 the write_concurrency option with the decentralized_counters
1233 option.
1234 Notice that this option does not change any guarantees about
1236 atomicity and isolation. Functions that makes such promises
1237 over many objects (like insert/2) gain less (or nothing)
1238 from this option.
1239 The memory consumption inflicted by both write_concurrency
1241 and read_concurrency is a constant overhead per table for
1242 set, bag and duplicate_bag when the true alternative for the
1243 write_concurrency option is not used. For all tables with
1244 the auto alternative and ordered_set tables with true alter‐
1245 native the memory overhead depends on the amount of actual
1246 detected concurrency during runtime. The memory overhead can
1247 be especially large when both write_concurrency and
1248 read_concurrency are combined.
1249 Note:
1251 Prior to stdlib-3.7 (OTP-22.0) write_concurrency had no effect
1252 on ordered_set.
1253 Note:
1256 The auto alternative for the write_concurrency option is only
1257 available in OTP-25.0 and above.
1258 {read_concurrency,boolean()}:
1261 Performance tuning. Defaults to false. When set to true, the
1262 table is optimized for concurrent read operations. When this
1263 option is enabled read operations become much cheaper; espe‐
1264 cially on systems with multiple physical processors. How‐
1265 ever, switching between read and write operations becomes
1266 more expensive.
1267 You typically want to enable this option when concurrent
1269 read operations are much more frequent than write opera‐
1270 tions, or when concurrent reads and writes comes in large
1271 read and write bursts (that is, many reads not interrupted
1272 by writes, and many writes not interrupted by reads).
1273 You typically do not want to enable this option when the
1275 common access pattern is a few read operations interleaved
1276 with a few write operations repeatedly. In this case, you
1277 would get a performance degradation by enabling this option.
1278 Option read_concurrency can be combined with option
1280 write_concurrency. You typically want to combine these when
1281 large concurrent read bursts and large concurrent write
1282 bursts are common.
1283 {decentralized_counters,boolean()}:
1285 Performance tuning. Defaults to true for all tables with the
1286 write_concurrency option set to auto. For tables of type or‐
1287 dered_set the option also defaults to true when the
1288 write_concurrency option is set to true. The option defaults
1289 to false for all other configurations. This option has no
1290 effect if the write_concurrency option is set to false.
1291 When this option is set to true, the table is optimized for
1293 frequent concurrent calls to operations that modify the ta‐
1294 bles size and/or its memory consumption (e.g., insert/2 and
1295 delete/2). The drawback is that calls to info/1 and info/2
1296 with size or memory as the second argument can get much
1297 slower when the decentralized_counters option is turned on.
1298 When this option is enabled the counters for the table size
1300 and memory consumption are distributed over several cache
1301 lines and the scheduling threads are mapped to one of those
1302 cache lines. The erl option +dcg can be used to control the
1303 number of cache lines that the counters are distributed
1304 over.
1305 compressed:
1307 If this option is present, the table data is stored in a
1308 more compact format to consume less memory. However, it will
1309 make table operations slower. Especially operations that
1310 need to inspect entire objects, such as match and select,
1311 get much slower. The key element is not compressed.
1312 next(Table, Key1) -> Key2 | '$end_of_table'
1314 Types:
1316 Table = table()
1318 Key1 = Key2 = term()
1319 Returns the next key Key2, following key Key1 in table Table.
1321 For table type ordered_set, the next key in Erlang term order is
1322 returned. For other table types, the next key according to the
1323 internal order of the table is returned. If no next key exists,
1324 '$end_of_table' is returned.
1325 To find the first key in the table, use first/1.
1327 Unless a table of type set, bag, or duplicate_bag is fixated us‐
1329 ing safe_fixtable/2, a call to next/2 will fail if Key1 no
1330 longer exists in the table. For table type ordered_set, the
1331 function always returns the next key after Key1 in term order,
1332 regardless whether Key1 ever existed in the table.
1333 prev(Table, Key1) -> Key2 | '$end_of_table'
1335 Types:
1337 Table = table()
1339 Key1 = Key2 = term()
1340 Returns the previous key Key2, preceding key Key1 according to
1342 Erlang term order in table Table of type ordered_set. For other
1343 table types, the function is synonymous to next/2. If no previ‐
1344 ous key exists, '$end_of_table' is returned.
1345 To find the last key in an ordered_set table, use last/1.
1347 rename(Table, Name) -> Name
1349 Types:
1351 Table = table()
1353 Name = atom()
1354 Renames the named table Table to the new name Name. Afterwards,
1356 the old name cannot be used to access the table. Renaming an un‐
1357 named table has no effect.
1358 repair_continuation(Continuation, MatchSpec) -> Continuation
1360 Types:
1362 Continuation = continuation()
1364 MatchSpec = match_spec()
1365 Restores an opaque continuation returned by select/3 or select/1
1367 if the continuation has passed through external term format
1368 (been sent between nodes or stored on disk).
1369 The reason for this function is that continuation terms contain
1371 compiled match specifications and may therefore be invalidated
1372 if converted to external term format. Given that the original
1373 match specification is kept intact, the continuation can be re‐
1374 stored, meaning it can once again be used in subsequent select/1
1375 calls even though it has been stored on disk or on another node.
1376 Examples:
1378 The following sequence of calls may fail:
1380 T=ets:new(x,[]),
1382 MS = ets:fun2ms(fun({N,_}=A) when (N rem 10) =:= 0 -> A end),
1383 {_,C} = ets:select(T, MS, 10),
1384 MaybeBroken = binary_to_term(term_to_binary(C)),
1385 ets:select(MaybeBroken).
1386 The following sequence works, as the call to repair_continua‐
1388 tion/2 reestablishes the MaybeBroken continuation.
1389 T=ets:new(x,[]),
1391 MS = ets:fun2ms(fun({N,_}=A) when (N rem 10) =:= 0 -> A end),
1392 {_,C} = ets:select(T,MS,10),
1393 MaybeBroken = binary_to_term(term_to_binary(C)),
1394 ets:select(ets:repair_continuation(MaybeBroken,MS)).
1395 Note:
1397 This function is rarely needed in application code. It is used
1398 by Mnesia to provide distributed select/3 and select/1 se‐
1399 quences. A normal application would either use Mnesia or keep
1400 the continuation from being converted to external format.
1401 The actual behavior of compiled match specifications when recre‐
1403 ated from external format has changed and may change in future
1404 releases, but this interface remains for backward compatibility.
1405 See is_compiled_ms/1.
1406 safe_fixtable(Table, Fix) -> true
1409 Types:
1411 Table = table()
1413 Fix = boolean()
1414 Fixes a table of type set, bag, or duplicate_bag for safe tra‐
1416 versal using first/1 & next/2, match/3 & match/1, match_object/3
1417 & match_object/1, or select/3 & select/1.
1418 A process fixes a table by calling safe_fixtable(Table, true).
1420 The table remains fixed until the process releases it by calling
1421 safe_fixtable(Table, false), or until the process terminates.
1422 If many processes fix a table, the table remains fixed until all
1424 processes have released it (or terminated). A reference counter
1425 is kept on a per process basis, and N consecutive fixes requires
1426 N releases to release the table.
1427 When a table is fixed, a sequence of first/1 and next/2 calls
1429 are guaranteed to succeed even if keys are removed during the
1430 traversal. The keys for objects inserted or deleted during a
1431 traversal may or may not be returned by next/2 depending on the
1432 ordering of keys within the table and if the key exists at the
1433 time next/2 is called.
1434 Example:
1436 clean_all_with_value(Table,X) ->
1438 safe_fixtable(Table,true),
1439 clean_all_with_value(Table,X,ets:first(Table)),
1440 safe_fixtable(Table,false).
1441 clean_all_with_value(Table,X,'$end_of_table') ->
1443 true;
1444 clean_all_with_value(Table,X,Key) ->
1445 case ets:lookup(Table,Key) of
1446 [{Key,X}] ->
1447 ets:delete(Table,Key);
1448 _ ->
1449 true
1450 end,
1451 clean_all_with_value(Table,X,ets:next(Table,Key)).
1452 Notice that deleted objects are not freed from a fixed table un‐
1454 til it has been released. If a process fixes a table but never
1455 releases it, the memory used by the deleted objects is never
1456 freed. The performance of operations on the table also degrades
1457 significantly.
1458 To retrieve information about which processes have fixed which
1460 tables, use info(Table, safe_fixed_monotonic_time). A system
1461 with many processes fixing tables can need a monitor that sends
1462 alarms when tables have been fixed for too long.
1463 Notice that safe_fixtable/2 is not necessary for table type or‐
1465 dered_set and for traversals done by a single ETS function call,
1466 like select/2.
1467 select(Continuation) -> {[Match], Continuation} | '$end_of_table'
1469 Types:
1471 Match = term()
1473 Continuation = continuation()
1474 Continues a match started with select/3. The next chunk of the
1476 size specified in the initial select/3 call is returned together
1477 with a new Continuation, which can be used in subsequent calls
1478 to this function.
1479 When there are no more objects in the table, '$end_of_table' is
1481 returned.
1482 select(Table, MatchSpec) -> [Match]
1484 Types:
1486 Table = table()
1488 MatchSpec = match_spec()
1489 Match = term()
1490 Matches the objects in table Table using a match specification.
1492 This is a more general call than match/2 and match_object/2
1493 calls. In its simplest form, the match specification is as fol‐
1494 lows:
1495 MatchSpec = [MatchFunction]
1497 MatchFunction = {MatchHead, [Guard], [Result]}
1498 MatchHead = "Pattern as in ets:match"
1499 Guard = {"Guardtest name", ...}
1500 Result = "Term construct"
1501 This means that the match specification is always a list of one
1503 or more tuples (of arity 3). The first element of the tuple is
1504 to be a pattern as described in match/2. The second element of
1505 the tuple is to be a list of 0 or more guard tests (described
1506 below). The third element of the tuple is to be a list contain‐
1507 ing a description of the value to return. In almost all normal
1508 cases, the list contains exactly one term that fully describes
1509 the value to return for each object.
1510 The return value is constructed using the "match variables"
1512 bound in MatchHead or using the special match variables '$_'
1513 (the whole matching object) and '$$' (all match variables in a
1514 list), so that the following match/2 expression:
1515 ets:match(Table,{'$1','$2','$3'})
1517 is exactly equivalent to:
1519 ets:select(Table,[{{'$1','$2','$3'},[],['$$']}])
1521 And that the following match_object/2 call:
1523 ets:match_object(Table,{'$1','$2','$1'})
1525 is exactly equivalent to
1527 ets:select(Table,[{{'$1','$2','$1'},[],['$_']}])
1529 Composite terms can be constructed in the Result part either by
1531 simply writing a list, so that the following code:
1532 ets:select(Table,[{{'$1','$2','$3'},[],['$$']}])
1534 gives the same output as:
1536 ets:select(Table,[{{'$1','$2','$3'},[],[['$1','$2','$3']]}])
1538 That is, all the bound variables in the match head as a list. If
1540 tuples are to be constructed, one has to write a tuple of arity
1541 1 where the single element in the tuple is the tuple one wants
1542 to construct (as an ordinary tuple can be mistaken for a Guard).
1543 Therefore the following call:
1545 ets:select(Table,[{{'$1','$2','$1'},[],['$_']}])
1547 gives the same output as:
1549 ets:select(Table,[{{'$1','$2','$1'},[],[{{'$1','$2','$3'}}]}])
1551 This syntax is equivalent to the syntax used in the trace pat‐
1553 terns (see the dbg(3)) module in Runtime_Tools.
1554 The Guards are constructed as tuples, where the first element is
1556 the test name and the remaining elements are the test parame‐
1557 ters. To check for a specific type (say a list) of the element
1558 bound to the match variable '$1', one would write the test as
1559 {is_list, '$1'}. If the test fails, the object in the table does
1560 not match and the next MatchFunction (if any) is tried. Most
1561 guard tests present in Erlang can be used, but only the new ver‐
1562 sions prefixed is_ are allowed (is_float, is_atom, and so on).
1563 The Guard section can also contain logic and arithmetic opera‐
1565 tions, which are written with the same syntax as the guard tests
1566 (prefix notation), so that the following guard test written in
1567 Erlang:
1568 is_integer(X), is_integer(Y), X + Y < 4711
1570 is expressed as follows (X replaced with '$1' and Y with '$2'):
1572 [{is_integer, '$1'}, {is_integer, '$2'}, {'<', {'+', '$1', '$2'}, 4711}]
1574 For tables of type ordered_set, objects are visited in the same
1576 order as in a first/next traversal. This means that the match
1577 specification is executed against objects with keys in the
1578 first/next order and the corresponding result list is in the or‐
1579 der of that execution.
1580 select(Table, MatchSpec, Limit) ->
1582 {[Match], Continuation} | '$end_of_table'
1583 Types:
1585 Table = table()
1587 MatchSpec = match_spec()
1588 Limit = integer() >= 1
1589 Match = term()
1590 Continuation = continuation()
1591 Works like select/2, but only returns a limited (Limit) number
1593 of matching objects. Term Continuation can then be used in sub‐
1594 sequent calls to select/1 to get the next chunk of matching ob‐
1595 jects. This is a space-efficient way to work on objects in a ta‐
1596 ble, which is still faster than traversing the table object by
1597 object using first/1 and next/2.
1598 If the table is empty, '$end_of_table' is returned.
1600 Use safe_fixtable/2 to guarantee safe traversal for subsequent
1602 calls to select/1.
1603 select_count(Table, MatchSpec) -> NumMatched
1605 Types:
1607 Table = table()
1609 MatchSpec = match_spec()
1610 NumMatched = integer() >= 0
1611 Matches the objects in table Table using a match specification.
1613 If the match specification returns true for an object, that ob‐
1614 ject considered a match and is counted. For any other result
1615 from the match specification the object is not considered a
1616 match and is therefore not counted.
1617 This function can be described as a select_delete/2 function
1619 that does not delete any elements, but only counts them.
1620 The function returns the number of objects matched.
1622 select_delete(Table, MatchSpec) -> NumDeleted
1624 Types:
1626 Table = table()
1628 MatchSpec = match_spec()
1629 NumDeleted = integer() >= 0
1630 Matches the objects in table Table using a match specification.
1632 If the match specification returns true for an object, that ob‐
1633 ject is removed from the table. For any other result from the
1634 match specification the object is retained. This is a more gen‐
1635 eral call than the match_delete/2 call.
1636 The function returns the number of objects deleted from the ta‐
1638 ble.
1639 Note:
1641 The match specification has to return the atom true if the ob‐
1642 ject is to be deleted. No other return value gets the object
1643 deleted. So one cannot use the same match specification for
1644 looking up elements as for deleting them.
1645 select_replace(Table, MatchSpec) -> NumReplaced
1648 Types:
1650 Table = table()
1652 MatchSpec = match_spec()
1653 NumReplaced = integer() >= 0
1654 Matches the objects in the table Table using a match specifica‐
1656 tion. For each matched object, the existing object is replaced
1657 with the match specification result.
1658 The match-and-replace operation for each individual object is
1660 guaranteed to be atomic and isolated. The select_replace table
1661 traversal as a whole, like all other select functions, does not
1662 give such guarantees.
1663 The match specification must be guaranteed to retain the key of
1665 any matched object. If not, select_replace will fail with badarg
1666 without updating any objects.
1667 For the moment, due to performance and semantic constraints, ta‐
1669 bles of type bag are not yet supported.
1670 The function returns the total number of replaced objects.
1672 Example
1674 For all 2-tuples with a list in second position, add atom
1676 'marker' first in the list:
1677 1> T = ets:new(x,[]), ets:insert(T, {key, [1, 2, 3]}).
1679 true
1680 2> MS = ets:fun2ms(fun({K, L}) when is_list(L) -> {K, [marker | L]} end).
1681 [{{'$1','$2'},[{is_list,'$2'}],[{{'$1',[marker|'$2']}}]}]
1682 3> ets:select_replace(T, MS).
1683 1
1684 4> ets:tab2list(T).
1685 [{key,[marker,1,2,3]}]
1686 A generic single object compare-and-swap operation:
1689 [Old] = ets:lookup(T, Key),
1691 New = update_object(Old),
1692 Success = (1 =:= ets:select_replace(T, [{Old, [], [{const, New}]}])),
1693 select_reverse(Continuation) ->
1696 {[Match], Continuation} | '$end_of_table'
1697 Types:
1699 Continuation = continuation()
1701 Match = term()
1702 Continues a match started with select_reverse/3. For tables of
1704 type ordered_set, the traversal of the table continues to ob‐
1705 jects with keys earlier in the Erlang term order. The returned
1706 list also contains objects with keys in reverse order. For all
1707 other table types, the behavior is exactly that of select/1.
1708 Example:
1710 1> T = ets:new(x,[ordered_set]).
1712 2> [ ets:insert(T,{N}) || N <- lists:seq(1,10) ].
1713 3> {R0,C0} = ets:select_reverse(T,[{'_',[],['$_']}],4).
1714 4> R0.
1715 [{10},{9},{8},{7}]
1716 5> {R1,C1} = ets:select_reverse(C0).
1717 6> R1.
1718 [{6},{5},{4},{3}]
1719 7> {R2,C2} = ets:select_reverse(C1).
1720 8> R2.
1721 [{2},{1}]
1722 9> '$end_of_table' = ets:select_reverse(C2).
1723 select_reverse(Table, MatchSpec) -> [Match]
1725 Types:
1727 Table = table()
1729 MatchSpec = match_spec()
1730 Match = term()
1731 Works like select/2, but returns the list in reverse order for
1733 table type ordered_set. For all other table types, the return
1734 value is identical to that of select/2.
1735 select_reverse(Table, MatchSpec, Limit) ->
1737 {[Match], Continuation} | '$end_of_table'
1738 Types:
1740 Table = table()
1742 MatchSpec = match_spec()
1743 Limit = integer() >= 1
1744 Match = term()
1745 Continuation = continuation()
1746 Works like select/3, but for table type ordered_set traversing
1748 is done starting at the last object in Erlang term order and
1749 moves to the first. For all other table types, the return value
1750 is identical to that of select/3.
1751 Notice that this is not equivalent to reversing the result list
1753 of a select/3 call, as the result list is not only reversed, but
1754 also contains the last Limit matching objects in the table, not
1755 the first.
1756 setopts(Table, Opts) -> true
1758 Types:
1760 Table = table()
1762 Opts = Opt | [Opt]
1763 Opt = {heir, pid(), HeirData} | {heir, none}
1764 HeirData = term()
1765 Sets table options. The only allowed option to be set after the
1767 table has been created is heir. The calling process must be the
1768 table owner.
1769 slot(Table, I) -> [Object] | '$end_of_table'
1771 Types:
1773 Table = table()
1775 I = integer() >= 0
1776 Object = tuple()
1777 This function is mostly for debugging purposes, Normally
1779 first/next or last/prev are to be used instead.
1780 Returns all objects in slot I of table Table. A table can be
1782 traversed by repeatedly calling the function, starting with the
1783 first slot I=0 and ending when '$end_of_table' is returned. If
1784 argument I is out of range, the function fails with reason
1785 badarg.
1786 Unless a table of type set, bag, or duplicate_bag is protected
1788 using safe_fixtable/2, a traversal can fail if concurrent up‐
1789 dates are made to the table. For table type ordered_set, the
1790 function returns a list containing object I in Erlang term or‐
1791 der.
1792 tab2file(Table, Filename) -> ok | {error, Reason}
1794 Types:
1796 Table = table()
1798 Filename = file:name()
1799 Reason = term()
1800 Dumps table Table to file Filename.
1802 Equivalent to tab2file(Table, Filename,[])
1804 tab2file(Table, Filename, Options) -> ok | {error, Reason}
1806 Types:
1808 Table = table()
1810 Filename = file:name()
1811 Options = [Option]
1812 Option = {extended_info, [ExtInfo]} | {sync, boolean()}
1813 ExtInfo = md5sum | object_count
1814 Reason = term()
1815 Dumps table Table to file Filename.
1817 When dumping the table, some information about the table is
1819 dumped to a header at the beginning of the dump. This informa‐
1820 tion contains data about the table type, name, protection, size,
1821 version, and if it is a named table. It also contains notes
1822 about what extended information is added to the file, which can
1823 be a count of the objects in the file or a MD5 sum of the header
1824 and records in the file.
1825 The size field in the header might not correspond to the number
1827 of records in the file if the table is public and records are
1828 added or removed from the table during dumping. Public tables
1829 updated during dump, and that one wants to verify when reading,
1830 needs at least one field of extended information for the read
1831 verification process to be reliable later.
1832 Option extended_info specifies what extra information is written
1834 to the table dump:
1835 object_count:
1837 The number of objects written to the file is noted in the
1838 file footer, so file truncation can be verified even if the
1839 file was updated during dump.
1840 md5sum:
1842 The header and objects in the file are checksummed using the
1843 built-in MD5 functions. The MD5 sum of all objects is writ‐
1844 ten in the file footer, so that verification while reading
1845 detects the slightest bitflip in the file data. Using this
1846 costs a fair amount of CPU time.
1847 Whenever option extended_info is used, it results in a file not
1849 readable by versions of ETS before that in STDLIB 1.15.1
1850 If option sync is set to true, it ensures that the content of
1852 the file is written to the disk before tab2file returns. De‐
1853 faults to {sync, false}.
1854 tab2list(Table) -> [Object]
1856 Types:
1858 Table = table()
1860 Object = tuple()
1861 Returns a list of all objects in table Table.
1863 tabfile_info(Filename) -> {ok, TableInfo} | {error, Reason}
1865 Types:
1867 Filename = file:name()
1869 TableInfo = [InfoItem]
1870 InfoItem =
1871 {name, atom()} |
1872 {type, Type} |
1873 {protection, Protection} |
1874 {named_table, boolean()} |
1875 {keypos, integer() >= 0} |
1876 {size, integer() >= 0} |
1877 {extended_info, [ExtInfo]} |
1878 {version,
1879 {Major :: integer() >= 0, Minor :: integer() >= 0}}
1880 ExtInfo = md5sum | object_count
1881 Type = bag | duplicate_bag | ordered_set | set
1882 Protection = private | protected | public
1883 Reason = term()
1884 Returns information about the table dumped to file by tab2file/2
1886 or tab2file/3.
1887 The following items are returned:
1889 name:
1891 The name of the dumped table. If the table was a named ta‐
1892 ble, a table with the same name cannot exist when the table
1893 is loaded from file with file2tab/2. If the table is not
1894 saved as a named table, this field has no significance when
1895 loading the table from file.
1896 type:
1898 The ETS type of the dumped table (that is, set, bag, dupli‐
1899 cate_bag, or ordered_set). This type is used when loading
1900 the table again.
1901 protection:
1903 The protection of the dumped table (that is, private, pro‐
1904 tected, or public). A table loaded from the file gets the
1905 same protection.
1906 named_table:
1908 true if the table was a named table when dumped to file,
1909 otherwise false. Notice that when a named table is loaded
1910 from a file, there cannot exist a table in the system with
1911 the same name.
1912 keypos:
1914 The keypos of the table dumped to file, which is used when
1915 loading the table again.
1916 size:
1918 The number of objects in the table when the table dump to
1919 file started. For a public table, this number does not need
1920 to correspond to the number of objects saved to the file, as
1921 objects can have been added or deleted by another process
1922 during table dump.
1923 extended_info:
1925 The extended information written in the file footer to allow
1926 stronger verification during table loading from file, as
1927 specified to tab2file/3. Notice that this function only
1928 tells which information is present, not the values in the
1929 file footer. The value is a list containing one or more of
1930 the atoms object_count and md5sum.
1931 version:
1933 A tuple {Major,Minor} containing the major and minor version
1934 of the file format for ETS table dumps. This version field
1935 was added beginning with STDLIB 1.5.1. Files dumped with
1936 older versions return {0,0} in this field.
1937 An error is returned if the file is inaccessible, badly damaged,
1939 or not produced with tab2file/2 or tab2file/3.
1940 table(Table) -> QueryHandle
1942 table(Table, Options) -> QueryHandle
1944 Types:
1946 Table = table()
1948 QueryHandle = qlc:query_handle()
1949 Options = [Option] | Option
1950 Option = {n_objects, NObjects} | {traverse, TraverseMethod}
1951 NObjects = default | integer() >= 1
1952 TraverseMethod =
1953 first_next | last_prev | select |
1954 {select, MatchSpec :: match_spec()}
1955 Returns a Query List Comprehension (QLC) query handle. The qlc
1957 module provides a query language aimed mainly at Mnesia, but ETS
1958 tables, Dets tables, and lists are also recognized by QLC as
1959 sources of data. Calling table/1,2 is the means to make the ETS
1960 table Table usable to QLC.
1961 When there are only simple restrictions on the key position, QLC
1963 uses lookup/2 to look up the keys. When that is not possible,
1964 the whole table is traversed. Option traverse determines how
1965 this is done:
1966 first_next:
1968 The table is traversed one key at a time by calling first/1
1969 and next/2.
1970 last_prev:
1972 The table is traversed one key at a time by calling last/1
1973 and prev/2.
1974 select:
1976 The table is traversed by calling select/3 and select/1. Op‐
1977 tion n_objects determines the number of objects returned
1978 (the third argument of select/3); the default is to return
1979 100 objects at a time. The match specification (the second
1980 argument of select/3) is assembled by QLC: simple filters
1981 are translated into equivalent match specifications while
1982 more complicated filters must be applied to all objects re‐
1983 turned by select/3 given a match specification that matches
1984 all objects.
1985 {select, MatchSpec}:
1987 As for select, the table is traversed by calling select/3
1988 and select/1. The difference is that the match specification
1989 is explicitly specified. This is how to state match specifi‐
1990 cations that cannot easily be expressed within the syntax
1991 provided by QLC.
1992 Examples:
1994 An explicit match specification is here used to traverse the ta‐
1996 ble:
1997 9> true = ets:insert(Table = ets:new(t, []), [{1,a},{2,b},{3,c},{4,d}]),
1999 MS = ets:fun2ms(fun({X,Y}) when (X > 1) or (X < 5) -> {Y} end),
2000 QH1 = ets:table(Table, [{traverse, {select, MS}}]).
2001 An example with an implicit match specification:
2003 10> QH2 = qlc:q([{Y} || {X,Y} <- ets:table(Table), (X > 1) or (X < 5)]).
2005 The latter example is equivalent to the former, which can be
2007 verified using function qlc:info/1:
2008 11> qlc:info(QH1) =:= qlc:info(QH2).
2010 true
2011 qlc:info/1 returns information about a query handle, and in this
2013 case identical information is returned for the two query han‐
2014 dles.
2015 take(Table, Key) -> [Object]
2017 Types:
2019 Table = table()
2021 Key = term()
2022 Object = tuple()
2023 Returns and removes a list of all objects with key Key in table
2025 Table.
2026 The specified Key is used to identify the object by either com‐
2028 paring equal the key of an object in an ordered_set table, or
2029 matching in other types of tables (for details on the differ‐
2030 ence, see lookup/2 and new/2).
2031 test_ms(Tuple, MatchSpec) -> {ok, Result} | {error, Errors}
2033 Types:
2035 Tuple = tuple()
2037 MatchSpec = match_spec()
2038 Result = term()
2039 Errors = [{warning | error, string()}]
2040 This function is a utility to test a match specification used in
2042 calls to select/2. The function both tests MatchSpec for "syn‐
2043 tactic" correctness and runs the match specification against ob‐
2044 ject Tuple.
2045 If the match specification is syntactically correct, the func‐
2047 tion either returns {ok,Result}, where Result is what would have
2048 been the result in a real select/2 call, or false if the match
2049 specification does not match object Tuple.
2050 If the match specification contains errors, tuple {error, Er‐
2052 rors} is returned, where Errors is a list of natural language
2053 descriptions of what was wrong with the match specification.
2054 This is a useful debugging and test tool, especially when writ‐
2056 ing complicated select/2 calls.
2057 See also: erlang:match_spec_test/3.
2059 to_dets(Table, DetsTab) -> DetsTab
2061 Types:
2063 Table = table()
2065 DetsTab = dets:tab_name()
2066 Fills an already created/opened Dets table with the objects in
2068 the already opened ETS table named Table. The Dets table is emp‐
2069 tied before the objects are inserted.
2070 update_counter(Table, Key, UpdateOp) -> Result
2072 update_counter(Table, Key, UpdateOp, Default) -> Result
2074 update_counter(Table, Key, X3 :: [UpdateOp]) -> [Result]
2076 update_counter(Table, Key, X3 :: [UpdateOp], Default) -> [Result]
2078 update_counter(Table, Key, Incr) -> Result
2080 update_counter(Table, Key, Incr, Default) -> Result
2082 Types:
2084 Table = table()
2086 Key = term()
2087 UpdateOp = {Pos, Incr} | {Pos, Incr, Threshold, SetValue}
2088 Pos = Incr = Threshold = SetValue = Result = integer()
2089 Default = tuple()
2090 This function provides an efficient way to update one or more
2092 counters, without the trouble of having to look up an object,
2093 update the object by incrementing an element, and insert the re‐
2094 sulting object into the table again. The operation is guaranteed
2095 to be atomic and isolated.
2096 This function destructively updates the object with key Key in
2098 table Table by adding Incr to the element at position Pos. The
2099 new counter value is returned. If no position is specified, the
2100 element directly following key (<keypos>+1) is updated.
2101 If a Threshold is specified, the counter is reset to value Set‐
2103 Value if the following conditions occur:
2104 * Incr is not negative (>= 0) and the result would be greater
2106 than (>) Threshold.
2107 * Incr is negative (< 0) and the result would be less than (<)
2109 Threshold.
2110 A list of UpdateOp can be supplied to do many update operations
2112 within the object. The operations are carried out in the order
2113 specified in the list. If the same counter position occurs more
2114 than once in the list, the corresponding counter is thus updated
2115 many times, each time based on the previous result. The return
2116 value is a list of the new counter values from each update oper‐
2117 ation in the same order as in the operation list. If an empty
2118 list is specified, nothing is updated and an empty list is re‐
2119 turned. If the function fails, no updates are done.
2120 The specified Key is used to identify the object by either
2122 matching the key of an object in a set table, or compare equal
2123 to the key of an object in an ordered_set table (for details on
2124 the difference, see lookup/2 and new/2).
2125 If a default object Default is specified, it is used as the ob‐
2127 ject to be updated if the key is missing from the table. The
2128 value in place of the key is ignored and replaced by the proper
2129 key value. The return value is as if the default object had not
2130 been used, that is, a single updated element or a list of them.
2131 The function fails with reason badarg in the following situa‐
2133 tions:
2134 * The table type is not set or ordered_set.
2136 * No object with the correct key exists and no default object
2138 was supplied.
2139 * The object has the wrong arity.
2141 * The default object arity is smaller than <keypos>.
2143 * Any field from the default object that is updated is not an
2145 integer.
2146 * The element to update is not an integer.
2148 * The element to update is also the key.
2150 * Any of Pos, Incr, Threshold, or SetValue is not an integer.
2152 update_element(Table, Key, ElementSpec :: {Pos, Value}) ->
2154 boolean()
2155 update_element(Table, Key, ElementSpec :: [{Pos, Value}]) ->
2157 boolean()
2158 Types:
2160 Table = table()
2162 Key = term()
2163 Value = term()
2164 Pos = integer() >= 1
2165 This function provides an efficient way to update one or more
2167 elements within an object, without the trouble of having to look
2168 up, update, and write back the entire object.
2169 This function destructively updates the object with key Key in
2171 table Table. The element at position Pos is given the value
2172 Value.
2173 A list of {Pos,Value} can be supplied to update many elements
2175 within the same object. If the same position occurs more than
2176 once in the list, the last value in the list is written. If the
2177 list is empty or the function fails, no updates are done. The
2178 function is also atomic in the sense that other processes can
2179 never see any intermediate results.
2180 Returns true if an object with key Key is found, otherwise
2182 false.
2183 The specified Key is used to identify the object by either
2185 matching the key of an object in a set table, or compare equal
2186 to the key of an object in an ordered_set table (for details on
2187 the difference, see lookup/2 and new/2).
2188 The function fails with reason badarg in the following situa‐
2190 tions:
2191 * The table type is not set or ordered_set.
2193 * Pos < 1.
2195 * Pos > object arity.
2197 * The element to update is also the key.
2199 whereis(TableName) -> tid() | undefined
2201 Types:
2203 TableName = atom()
2205 This function returns the tid() of the named table identified by
2207 TableName, or undefined if no such table exists. The tid() can
2208 be used in place of the table name in all operations, which is
2209 slightly faster since the name does not have to be resolved on
2210 each call.
2211 If the table is deleted, the tid() will be invalid even if an‐
2213 other named table is created with the same name.
2214Ericsson AB stdlib 5.1.1 ets(3)