1dets(3) Erlang Module Definition dets(3)
2
6 dets - A disk-based term storage.
7
9 This module provides a term storage on file. The stored terms, in this
10 module called objects, are tuples such that one element is defined to
11 be the key. A Dets table is a collection of objects with the key at the
12 same position stored on a file.
13 This module is used by the Mnesia application, and is provided "as is"
15 for users who are interested in efficient storage of Erlang terms on
16 disk only. Many applications only need to store some terms in a file.
17 Mnesia adds transactions, queries, and distribution. The size of Dets
18 files cannot exceed 2 GB. If larger tables are needed, table fragmenta‐
19 tion in Mnesia can be used.
20 Three types of Dets tables exist:
22 * set. A table of this type has at most one object with a given key.
24 If an object with a key already present in the table is inserted,
25 the existing object is overwritten by the new object.
26 * bag. A table of this type has zero or more different objects with a
28 given key.
29 * duplicate_bag. A table of this type has zero or more possibly
31 matching objects with a given key.
32 Dets tables must be opened before they can be updated or read, and when
34 finished they must be properly closed. If a table is not properly
35 closed, Dets automatically repairs the table. This can take a substan‐
36 tial time if the table is large. A Dets table is closed when the
37 process which opened the table terminates. If many Erlang processes
38 (users) open the same Dets table, they share the table. The table is
39 properly closed when all users have either terminated or closed the ta‐
40 ble. Dets tables are not properly closed if the Erlang runtime system
41 terminates abnormally.
42 Note:
44 A ^C command abnormally terminates an Erlang runtime system in a Unix
45 environment with a break-handler.
46 As all operations performed by Dets are disk operations, it is impor‐
49 tant to realize that a single look-up operation involves a series of
50 disk seek and read operations. The Dets functions are therefore much
51 slower than the corresponding ets(3) functions, although Dets exports a
52 similar interface.
53 Dets organizes data as a linear hash list and the hash list grows
55 gracefully as more data is inserted into the table. Space management on
56 the file is performed by what is called a buddy system. The current
57 implementation keeps the entire buddy system in RAM, which implies that
58 if the table gets heavily fragmented, quite some memory can be used up.
59 The only way to defragment a table is to close it and then open it
60 again with option repair set to force.
61 Notice that type ordered_set in Ets is not yet provided by Dets, nei‐
63 ther is the limited support for concurrent updates that makes a
64 sequence of first and next calls safe to use on fixed ETS tables. Both
65 these features may be provided by Dets in a future release of
66 Erlang/OTP. Until then, the Mnesia application (or some user-imple‐
67 mented method for locking) must be used to implement safe concurrency.
68 Currently, no Erlang/OTP library has support for ordered disk-based
69 term storage.
70 All Dets functions return {error, Reason} if an error occurs (first/1
72 and next/2 are exceptions, they exit the process with the error tuple).
73 If badly formed arguments are specified, all functions exit the process
74 with a badarg message.
75
77 access() = read | read_write
78 auto_save() = infinity | integer() >= 0
80 bindings_cont()
82 Opaque continuation used by match/1 and match/3.
84 cont()
86 Opaque continuation used by bchunk/2.
88 keypos() = integer() >= 1
90 match_spec() = ets:match_spec()
92 Match specifications, see section Match Specification in Erlang
94 in ERTS User's Guide and the ms_transform(3) module.
95 no_slots() = default | integer() >= 0
97 object() = tuple()
99 object_cont()
101 Opaque continuation used by match_object/1 and match_object/3.
103 pattern() = atom() | tuple()
105 For a description of patterns, see ets:match/2.
107 select_cont()
109 Opaque continuation used by select/1 and select/3.
111 tab_name() = term()
113 type() = bag | duplicate_bag | set
115
117 all() -> [tab_name()]
118 Returns a list of the names of all open tables on this node.
120 bchunk(Name, Continuation) ->
122 {Continuation2, Data} |
123 '$end_of_table' |
124 {error, Reason}
125 Types:
127 Name = tab_name()
129 Continuation = start | cont()
130 Continuation2 = cont()
131 Data = binary() | tuple()
132 Reason = term()
133 Returns a list of objects stored in a table. The exact represen‐
135 tation of the returned objects is not public. The lists of data
136 can be used for initializing a table by specifying value bchunk
137 to option format of function init_table/3 The Mnesia application
138 uses this function for copying open tables.
139 Unless the table is protected using safe_fixtable/2, calls to
141 bchunk/2 do possibly not work as expected if concurrent updates
142 are made to the table.
143 The first time bchunk/2 is called, an initial continuation, the
145 atom start, must be provided.
146 bchunk/2 returns a tuple {Continuation2, Data}, where Data is a
148 list of objects. Continuation2 is another continuation that is
149 to be passed on to a subsequent call to bchunk/2. With a series
150 of calls to bchunk/2, all table objects can be extracted.
151 bchunk/2 returns '$end_of_table' when all objects are returned,
153 or {error, Reason} if an error occurs.
154 close(Name) -> ok | {error, Reason}
156 Types:
158 Name = tab_name()
160 Reason = term()
161 Closes a table. Only processes that have opened a table are
163 allowed to close it.
164 All open tables must be closed before the system is stopped. If
166 an attempt is made to open a table that is not properly closed,
167 Dets automatically tries to repair it.
168 delete(Name, Key) -> ok | {error, Reason}
170 Types:
172 Name = tab_name()
174 Key = Reason = term()
175 Deletes all objects with key Key from table Name.
177 delete_all_objects(Name) -> ok | {error, Reason}
179 Types:
181 Name = tab_name()
183 Reason = term()
184 Deletes all objects from a table in almost constant time. How‐
186 ever, if the table if fixed, delete_all_objects(T) is equivalent
187 to match_delete(T, '_').
188 delete_object(Name, Object) -> ok | {error, Reason}
190 Types:
192 Name = tab_name()
194 Object = object()
195 Reason = term()
196 Deletes all instances of a specified object from a table. If a
198 table is of type bag or duplicate_bag, this function can be used
199 to delete only some of the objects with a specified key.
200 first(Name) -> Key | '$end_of_table'
202 Types:
204 Name = tab_name()
206 Key = term()
207 Returns the first key stored in table Name according to the
209 internal order of the table, or '$end_of_table' if the table is
210 empty.
211 Unless the table is protected using safe_fixtable/2, subsequent
213 calls to next/2 do possibly not work as expected if concurrent
214 updates are made to the table.
215 If an error occurs, the process is exited with an error tuple
217 {error, Reason}. The error tuple is not returned, as it cannot
218 be distinguished from a key.
219 There are two reasons why first/1 and next/2 are not to be used:
221 they are not efficient, and they prevent the use of key
222 '$end_of_table', as this atom is used to indicate the end of the
223 table. If possible, use functions match, match_object, and
224 select for traversing tables.
225 foldl(Function, Acc0, Name) -> Acc | {error, Reason}
227 foldr(Function, Acc0, Name) -> Acc | {error, Reason}
229 Types:
231 Name = tab_name()
233 Function = fun((Object :: object(), AccIn) -> AccOut)
234 Acc0 = Acc = AccIn = AccOut = Reason = term()
235 Calls Function on successive elements of table Name together
237 with an extra argument AccIn. The table elements are traversed
238 in unspecified order. Function must return a new accumulator
239 that is passed to the next call. Acc0 is returned if the table
240 is empty.
241 from_ets(Name, EtsTab) -> ok | {error, Reason}
243 Types:
245 Name = tab_name()
247 EtsTab = ets:tab()
248 Reason = term()
249 Deletes all objects of table Name and then inserts all the
251 objects of the ETS table EtsTab. The objects are inserted in
252 unspecified order. As ets:safe_fixtable/2 is called, the ETS ta‐
253 ble must be public or owned by the calling process.
254 info(Name) -> InfoList | undefined
256 Types:
258 Name = tab_name()
260 InfoList = [InfoTuple]
261 InfoTuple =
262 {file_size, integer() >= 0} |
263 {filename, file:name()} |
264 {keypos, keypos()} |
265 {size, integer() >= 0} |
266 {type, type()}
267 Returns information about table Name as a list of tuples:
269 * {file_size, integer() >= 0}} - The file size, in bytes.
271 * {filename, file:name()} - The name of the file where objects
273 are stored.
274 * {keypos, keypos()} - The key position.
276 * {size, integer() >= 0} - The number of objects stored in the
278 table.
279 * {type, type()} - The table type.
281 info(Name, Item) -> Value | undefined
283 Types:
285 Name = tab_name()
287 Item =
288 access |
289 auto_save |
290 bchunk_format |
291 hash |
292 file_size |
293 filename |
294 keypos |
295 memory |
296 no_keys |
297 no_objects |
298 no_slots |
299 owner |
300 ram_file |
301 safe_fixed |
302 safe_fixed_monotonic_time |
303 size |
304 type
305 Value = term()
306 Returns the information associated with Item for table Name. In
308 addition to the {Item, Value} pairs defined for info/1, the fol‐
309 lowing items are allowed:
310 * {access, access()} - The access mode.
312 * {auto_save, auto_save()} - The autosave interval.
314 * {bchunk_format, binary()} - An opaque binary describing the
316 format of the objects returned by bchunk/2. The binary can
317 be used as argument to is_compatible_chunk_format/2.
318 * {hash, Hash} - Describes which BIF is used to calculate the
320 hash values of the objects stored in the Dets table. Possi‐
321 ble values of Hash:
322 * phash - Implies that the erlang:phash/2 BIF is used.
324 * phash2 - Implies that the erlang:phash2/1 BIF is used.
326 * {memory, integer() >= 0} - The file size, in bytes. The same
328 value is associated with item file_size.
329 * {no_keys, integer >= 0()} - The number of different keys
331 stored in the table.
332 * {no_objects, integer >= 0()} - The number of objects stored
334 in the table.
335 * {no_slots, {Min, Used, Max}} - The number of slots of the
337 table. Min is the minimum number of slots, Used is the num‐
338 ber of currently used slots, and Max is the maximum number
339 of slots.
340 * {owner, pid()} - The pid of the process that handles
342 requests to the Dets table.
343 * {ram_file, boolean()} - Whether the table is kept in RAM.
345 * {safe_fixed_monotonic_time, SafeFixed} - If the table is
347 fixed, SafeFixed is a tuple {FixedAtTime, [{Pid,RefCount}]}.
348 FixedAtTime is the time when the table was first fixed, and
349 Pid is the pid of the process that fixes the table RefCount
350 times. There can be any number of processes in the list. If
351 the table is not fixed, SafeFixed is the atom false.
352 FixedAtTime corresponds to the result returned by
354 erlang:monotonic_time/0 at the time of fixation. The use of
355 safe_fixed_monotonic_time is time warp safe.
356 * {safe_fixed, SafeFixed} - The same as {safe_fixed_mono‐
358 tonic_time, SafeFixed} except the format and value of Fixe‐
359 dAtTime.
360 FixedAtTime corresponds to the result returned by
362 erlang:timestamp/0 at the time of fixation. Notice that when
363 the system uses single or multi time warp modes, this can
364 produce strange results. This is because the use of
365 safe_fixed is not time warp safe. Time warp safe code must
366 use safe_fixed_monotonic_time instead.
367 init_table(Name, InitFun) -> ok | {error, Reason}
369 init_table(Name, InitFun, Options) -> ok | {error, Reason}
371 Types:
373 Name = tab_name()
375 InitFun = fun((Arg) -> Res)
376 Arg = read | close
377 Res =
378 end_of_input |
379 {[object()], InitFun} |
380 {Data, InitFun} |
381 term()
382 Options = Option | [Option]
383 Option = {min_no_slots, no_slots()} | {format, term | bchunk}
384 Reason = term()
385 Data = binary() | tuple()
386 Replaces the existing objects of table Name with objects created
388 by calling the input function InitFun, see below. The reason for
389 using this function rather than calling insert/2 is that of
390 efficiency. Notice that the input functions are called by the
391 process that handles requests to the Dets table, not by the
392 calling process.
393 When called with argument read, function InitFun is assumed to
395 return end_of_input when there is no more input, or {Objects,
396 Fun}, where Objects is a list of objects and Fun is a new input
397 function. Any other value Value is returned as an error {error,
398 {init_fun, Value}}. Each input function is called exactly once,
399 and if an error occurs, the last function is called with argu‐
400 ment close, the reply of which is ignored.
401 If the table type is set and more than one object exists with a
403 given key, one of the objects is chosen. This is not necessarily
404 the last object with the given key in the sequence of objects
405 returned by the input functions. Avoid duplicate keys, otherwise
406 the file becomes unnecessarily fragmented. This holds also for
407 duplicated objects stored in tables of type bag.
408 It is important that the table has a sufficient number of slots
410 for the objects. If not, the hash list starts to grow when
411 init_table/2 returns, which significantly slows down access to
412 the table for a period of time. The minimum number of slots is
413 set by the open_file/2 option min_no_slots and returned by the
414 info/2 item no_slots. See also option min_no_slots below.
415 Argument Options is a list of {Key, Val} tuples, where the fol‐
417 lowing values are allowed:
418 * {min_no_slots, no_slots()} - Specifies the estimated number
420 of different keys to be stored in the table. The open_file/2
421 option with the same name is ignored, unless the table is
422 created, in which case performance can be enhanced by sup‐
423 plying an estimate when initializing the table.
424 * {format, Format} - Specifies the format of the objects
426 returned by function InitFun. If Format is term (the
427 default), InitFun is assumed to return a list of tuples. If
428 Format is bchunk, InitFun is assumed to return Data as
429 returned by bchunk/2. This option overrides option
430 min_no_slots.
431 insert(Name, Objects) -> ok | {error, Reason}
433 Types:
435 Name = tab_name()
437 Objects = object() | [object()]
438 Reason = term()
439 Inserts one or more objects into the table Name. If there
441 already exists an object with a key matching the key of some of
442 the given objects and the table type is set, the old object will
443 be replaced.
444 insert_new(Name, Objects) -> boolean() | {error, Reason}
446 Types:
448 Name = tab_name()
450 Objects = object() | [object()]
451 Reason = term()
452 Inserts one or more objects into table Name. If there already
454 exists some object with a key matching the key of any of the
455 specified objects, the table is not updated and false is
456 returned. Otherwise the objects are inserted and true returned.
457 is_compatible_bchunk_format(Name, BchunkFormat) -> boolean()
459 Types:
461 Name = tab_name()
463 BchunkFormat = binary()
464 Returns true if it would be possible to initialize table Name,
466 using init_table/3 with option {format, bchunk}, with objects
467 read with bchunk/2 from some table T, such that calling info(T,
468 bchunk_format) returns BchunkFormat.
469 is_dets_file(Filename) -> boolean() | {error, Reason}
471 Types:
473 Filename = file:name()
475 Reason = term()
476 Returns true if file Filename is a Dets table, otherwise false.
478 lookup(Name, Key) -> Objects | {error, Reason}
480 Types:
482 Name = tab_name()
484 Key = term()
485 Objects = [object()]
486 Reason = term()
487 Returns a list of all objects with key Key stored in table Name,
489 for example:
490 2> dets:open_file(abc, [{type, bag}]).
492 {ok,abc}
493 3> dets:insert(abc, {1,2,3}).
494 ok
495 4> dets:insert(abc, {1,3,4}).
496 ok
497 5> dets:lookup(abc, 1).
498 [{1,2,3},{1,3,4}]
499 If the table type is set, the function returns either the empty
501 list or a list with one object, as there cannot be more than one
502 object with a given key. If the table type is bag or dupli‐
503 cate_bag, the function returns a list of arbitrary length.
504 Notice that the order of objects returned is unspecified. In
506 particular, the order in which objects were inserted is not
507 reflected.
508 match(Continuation) ->
510 {[Match], Continuation2} |
511 '$end_of_table' |
512 {error, Reason}
513 Types:
515 Continuation = Continuation2 = bindings_cont()
517 Match = [term()]
518 Reason = term()
519 Matches some objects stored in a table and returns a non-empty
521 list of the bindings matching a specified pattern in some
522 unspecified order. The table, the pattern, and the number of
523 objects that are matched are all defined by Continuation, which
524 has been returned by a previous call to match/1 or match/3.
525 When all table objects are matched, '$end_of_table' is returned.
527 match(Name, Pattern) -> [Match] | {error, Reason}
529 Types:
531 Name = tab_name()
533 Pattern = pattern()
534 Match = [term()]
535 Reason = term()
536 Returns for each object of table Name that matches Pattern a
538 list of bindings in some unspecified order. For a description of
539 patterns, see ets:match/2. If the keypos'th element of Pattern
540 is unbound, all table objects are matched. If the keypos'th ele‐
541 ment is bound, only the objects with the correct key are
542 matched.
543 match(Name, Pattern, N) ->
545 {[Match], Continuation} |
546 '$end_of_table' |
547 {error, Reason}
548 Types:
550 Name = tab_name()
552 Pattern = pattern()
553 N = default | integer() >= 0
554 Continuation = bindings_cont()
555 Match = [term()]
556 Reason = term()
557 Matches some or all objects of table Name and returns a non-
559 empty list of the bindings that match Pattern in some unspeci‐
560 fied order. For a description of patterns, see ets:match/2.
561 A tuple of the bindings and a continuation is returned, unless
563 the table is empty, in which case '$end_of_table' is returned.
564 The continuation is to be used when matching further objects by
565 calling match/1.
566 If the keypos'th element of Pattern is bound, all table objects
568 are matched. If the keypos'th element is unbound, all table
569 objects are matched, N objects at a time, until at least one
570 object matches or the end of the table is reached. The default,
571 indicated by giving N the value default, is to let the number of
572 objects vary depending on the sizes of the objects. All objects
573 with the same key are always matched at the same time, which
574 implies that more than N objects can sometimes be matched.
575 The table is always to be protected using safe_fixtable/2 before
577 calling match/3, otherwise errors can occur when calling
578 match/1.
579 match_delete(Name, Pattern) -> ok | {error, Reason}
581 Types:
583 Name = tab_name()
585 Pattern = pattern()
586 Reason = term()
587 Deletes all objects that match Pattern from table Name. For a
589 description of patterns, see ets:match/2.
590 If the keypos'th element of Pattern is bound, only the objects
592 with the correct key are matched.
593 match_object(Continuation) ->
595 {Objects, Continuation2} |
596 '$end_of_table' |
597 {error, Reason}
598 Types:
600 Continuation = Continuation2 = object_cont()
602 Objects = [object()]
603 Reason = term()
604 Returns a non-empty list of some objects stored in a table that
606 match a given pattern in some unspecified order. The table, the
607 pattern, and the number of objects that are matched are all
608 defined by Continuation, which has been returned by a previous
609 call to match_object/1 or match_object/3.
610 When all table objects are matched, '$end_of_table' is returned.
612 match_object(Name, Pattern) -> Objects | {error, Reason}
614 Types:
616 Name = tab_name()
618 Pattern = pattern()
619 Objects = [object()]
620 Reason = term()
621 Returns a list of all objects of table Name that match Pattern
623 in some unspecified order. For a description of patterns, see
624 ets:match/2.
625 If the keypos'th element of Pattern is unbound, all table
627 objects are matched. If the keypos'th element of Pattern is
628 bound, only the objects with the correct key are matched.
629 Using the match_object functions for traversing all table
631 objects is more efficient than calling first/1 and next/2 or
632 slot/2.
633 match_object(Name, Pattern, N) ->
635 {Objects, Continuation} |
636 '$end_of_table' |
637 {error, Reason}
638 Types:
640 Name = tab_name()
642 Pattern = pattern()
643 N = default | integer() >= 0
644 Continuation = object_cont()
645 Objects = [object()]
646 Reason = term()
647 Matches some or all objects stored in table Name and returns a
649 non-empty list of the objects that match Pattern in some unspec‐
650 ified order. For a description of patterns, see ets:match/2.
651 A list of objects and a continuation is returned, unless the ta‐
653 ble is empty, in which case '$end_of_table' is returned. The
654 continuation is to be used when matching further objects by
655 calling match_object/1.
656 If the keypos'th element of Pattern is bound, all table objects
658 are matched. If the keypos'th element is unbound, all table
659 objects are matched, N objects at a time, until at least one
660 object matches or the end of the table is reached. The default,
661 indicated by giving N the value default, is to let the number of
662 objects vary depending on the sizes of the objects. All matching
663 objects with the same key are always returned in the same reply,
664 which implies that more than N objects can sometimes be
665 returned.
666 The table is always to be protected using safe_fixtable/2 before
668 calling match_object/3, otherwise errors can occur when calling
669 match_object/1.
670 member(Name, Key) -> boolean() | {error, Reason}
672 Types:
674 Name = tab_name()
676 Key = Reason = term()
677 Works like lookup/2, but does not return the objects. Returns
679 true if one or more table elements has key Key, otherwise false.
680 next(Name, Key1) -> Key2 | '$end_of_table'
682 Types:
684 Name = tab_name()
686 Key1 = Key2 = term()
687 Returns either the key following Key1 in table Name according to
689 the internal order of the table, or '$end_of_table' if there is
690 no next key.
691 If an error occurs, the process is exited with an error tuple
693 {error, Reason}.
694 To find the first key in the table, use first/1.
696 open_file(Filename) -> {ok, Reference} | {error, Reason}
698 Types:
700 Filename = file:name()
702 Reference = reference()
703 Reason = term()
704 Opens an existing table. If the table is not properly closed, it
706 is repaired. The returned reference is to be used as the table
707 name. This function is most useful for debugging purposes.
708 open_file(Name, Args) -> {ok, Name} | {error, Reason}
710 Types:
712 Name = tab_name()
714 Args = [OpenArg]
715 OpenArg =
716 {access, access()} |
717 {auto_save, auto_save()} |
718 {estimated_no_objects, integer() >= 0} |
719 {file, file:name()} |
720 {max_no_slots, no_slots()} |
721 {min_no_slots, no_slots()} |
722 {keypos, keypos()} |
723 {ram_file, boolean()} |
724 {repair, boolean() | force} |
725 {type, type()}
726 Reason = term()
727 Opens a table. An empty Dets table is created if no file exists.
729 The atom Name is the table name. The table name must be provided
731 in all subsequent operations on the table. The name can be used
732 by other processes as well, and many processes can share one ta‐
733 ble.
734 If two processes open the same table by giving the same name and
736 arguments, the table has two users. If one user closes the ta‐
737 ble, it remains open until the second user closes it.
738 Argument Args is a list of {Key, Val} tuples, where the follow‐
740 ing values are allowed:
741 * {access, access()} - Existing tables can be opened in read-
743 only mode. A table that is opened in read-only mode is not
744 subjected to the automatic file reparation algorithm if it
745 is later opened after a crash. Defaults to read_write.
746 * {auto_save, auto_save()} - The autosave interval. If the
748 interval is an integer Time, the table is flushed to disk
749 whenever it is not accessed for Time milliseconds. A table
750 that has been flushed requires no reparation when reopened
751 after an uncontrolled emulator halt. If the interval is the
752 atom infinity, autosave is disabled. Defaults to 180000 (3
753 minutes).
754 * {estimated_no_objects, no_slots()} - Equivalent to option
756 min_no_slots.
757 * {file, file:name()} - The name of the file to be opened.
759 Defaults to the table name.
760 * {max_no_slots, no_slots()} - The maximum number of slots to
762 be used. Defaults to 32 M, which is the maximal value.
763 Notice that a higher value can increase the table fragmenta‐
764 tion, and a smaller value can decrease the fragmentation, at
765 the expense of execution time.
766 * {min_no_slots, no_slots()} - Application performance can be
768 enhanced with this flag by specifying, when the table is
769 created, the estimated number of different keys to be stored
770 in the table. Defaults to 256, which is the minimum value.
771 * {keypos, keypos()} - The position of the element of each
773 object to be used as key. Defaults to 1. The ability to
774 explicitly state the key position is most convenient when we
775 want to store Erlang records in which the first position of
776 the record is the name of the record type.
777 * {ram_file, boolean()} - Whether the table is to be kept in
779 RAM. Keeping the table in RAM can sound like an anomaly, but
780 can enhance the performance of applications that open a ta‐
781 ble, insert a set of objects, and then close the table. When
782 the table is closed, its contents are written to the disk
783 file. Defaults to false.
784 * {repair, Value} - Value can be either a boolean() or the
786 atom force. The flag specifies if the Dets server is to
787 invoke the automatic file reparation algorithm. Defaults to
788 true. If false is specified, no attempt is made to repair
789 the file, and {error, {needs_repair, FileName}} is returned
790 if the table must be repaired.
791 Value force means that a reparation is made even if the ta‐
793 ble is properly closed. This is a seldom needed option.
794 Option repair is ignored if the table is already open.
796 * {type, type()} - The table type. Defaults to set.
798 pid2name(Pid) -> {ok, Name} | undefined
800 Types:
802 Pid = pid()
804 Name = tab_name()
805 Returns the table name given the pid of a process that handles
807 requests to a table, or undefined if there is no such table.
808 This function is meant to be used for debugging only.
810 repair_continuation(Continuation, MatchSpec) -> Continuation2
812 Types:
814 Continuation = Continuation2 = select_cont()
816 MatchSpec = match_spec()
817 This function can be used to restore an opaque continuation
819 returned by select/3 or select/1 if the continuation has passed
820 through external term format (been sent between nodes or stored
821 on disk).
822 The reason for this function is that continuation terms contain
824 compiled match specifications and therefore are invalidated if
825 converted to external term format. Given that the original match
826 specification is kept intact, the continuation can be restored,
827 meaning it can once again be used in subsequent select/1 calls
828 even though it has been stored on disk or on another node.
829 For more information and examples, see the ets(3) module.
831 Note:
833 This function is rarely needed in application code. It is used
834 by application Mnesia to provide distributed select/3 and
835 select/1 sequences. A normal application would either use Mnesia
836 or keep the continuation from being converted to external for‐
837 mat.
838 The reason for not having an external representation of compiled
840 match specifications is performance. It can be subject to change
841 in future releases, while this interface remains for backward
842 compatibility.
843 safe_fixtable(Name, Fix) -> ok
846 Types:
848 Name = tab_name()
850 Fix = boolean()
851 If Fix is true, table Name is fixed (once more) by the calling
853 process, otherwise the table is released. The table is also
854 released when a fixing process terminates.
855 If many processes fix a table, the table remains fixed until all
857 processes have released it or terminated. A reference counter is
858 kept on a per process basis, and N consecutive fixes require N
859 releases to release the table.
860 It is not guaranteed that calls to first/1, next/2, or select
862 and match functions work as expected even if the table is fixed;
863 the limited support for concurrency provided by the ets(3) mod‐
864 ule is not yet provided by Dets. Fixing a table currently only
865 disables resizing of the hash list of the table.
866 If objects have been added while the table was fixed, the hash
868 list starts to grow when the table is released, which signifi‐
869 cantly slows down access to the table for a period of time.
870 select(Continuation) ->
872 {Selection, Continuation2} |
873 '$end_of_table' |
874 {error, Reason}
875 Types:
877 Continuation = Continuation2 = select_cont()
879 Selection = [term()]
880 Reason = term()
881 Applies a match specification to some objects stored in a table
883 and returns a non-empty list of the results. The table, the
884 match specification, and the number of objects that are matched
885 are all defined by Continuation, which is returned by a previous
886 call to select/1 or select/3.
887 When all objects of the table have been matched, '$end_of_table'
889 is returned.
890 select(Name, MatchSpec) -> Selection | {error, Reason}
892 Types:
894 Name = tab_name()
896 MatchSpec = match_spec()
897 Selection = [term()]
898 Reason = term()
899 Returns the results of applying match specification MatchSpec to
901 all or some objects stored in table Name. The order of the
902 objects is not specified. For a description of match specifica‐
903 tions, see the ERTS User's Guide.
904 If the keypos'th element of MatchSpec is unbound, the match
906 specification is applied to all objects of the table. If the
907 keypos'th element is bound, the match specification is applied
908 to the objects with the correct key(s) only.
909 Using the select functions for traversing all objects of a table
911 is more efficient than calling first/1 and next/2 or slot/2.
912 select(Name, MatchSpec, N) ->
914 {Selection, Continuation} |
915 '$end_of_table' |
916 {error, Reason}
917 Types:
919 Name = tab_name()
921 MatchSpec = match_spec()
922 N = default | integer() >= 0
923 Continuation = select_cont()
924 Selection = [term()]
925 Reason = term()
926 Returns the results of applying match specification MatchSpec to
928 some or all objects stored in table Name. The order of the
929 objects is not specified. For a description of match specifica‐
930 tions, see the ERTS User's Guide.
931 A tuple of the results of applying the match specification and a
933 continuation is returned, unless the table is empty, in which
934 case '$end_of_table' is returned. The continuation is to be used
935 when matching more objects by calling select/1.
936 If the keypos'th element of MatchSpec is bound, the match speci‐
938 fication is applied to all objects of the table with the correct
939 key(s). If the keypos'th element of MatchSpec is unbound, the
940 match specification is applied to all objects of the table, N
941 objects at a time, until at least one object matches or the end
942 of the table is reached. The default, indicated by giving N the
943 value default, is to let the number of objects vary depending on
944 the sizes of the objects. All objects with the same key are
945 always handled at the same time, which implies that the match
946 specification can be applied to more than N objects.
947 The table is always to be protected using safe_fixtable/2 before
949 calling select/3, otherwise errors can occur when calling
950 select/1.
951 select_delete(Name, MatchSpec) -> N | {error, Reason}
953 Types:
955 Name = tab_name()
957 MatchSpec = match_spec()
958 N = integer() >= 0
959 Reason = term()
960 Deletes each object from table Name such that applying match
962 specification MatchSpec to the object returns value true. For a
963 description of match specifications, see the ERTS User's Guide.
964 Returns the number of deleted objects.
965 If the keypos'th element of MatchSpec is bound, the match speci‐
967 fication is applied to the objects with the correct key(s) only.
968 slot(Name, I) -> '$end_of_table' | Objects | {error, Reason}
970 Types:
972 Name = tab_name()
974 I = integer() >= 0
975 Objects = [object()]
976 Reason = term()
977 The objects of a table are distributed among slots, starting
979 with slot 0 and ending with slot n. Returns the list of objects
980 associated with slot I. If I > n, '$end_of_table' is returned.
981 sync(Name) -> ok | {error, Reason}
983 Types:
985 Name = tab_name()
987 Reason = term()
988 Ensures that all updates made to table Name are written to disk.
990 This also applies to tables that have been opened with flag
991 ram_file set to true. In this case, the contents of the RAM file
992 are flushed to disk.
993 Notice that the space management data structures kept in RAM,
995 the buddy system, is also written to the disk. This can take
996 some time if the table is fragmented.
997 table(Name) -> QueryHandle
999 table(Name, Options) -> QueryHandle
1001 Types:
1003 Name = tab_name()
1005 Options = Option | [Option]
1006 Option = {n_objects, Limit} | {traverse, TraverseMethod}
1007 Limit = default | integer() >= 1
1008 TraverseMethod = first_next | select | {select, match_spec()}
1009 QueryHandle = qlc:query_handle()
1010 Returns a Query List Comprehension (QLC) query handle. The
1012 qlc(3) module provides a query language aimed mainly for Mnesia,
1013 but ETS tables, Dets tables, and lists are also recognized by
1014 qlc as sources of data. Calling dets:table/1,2 is the means to
1015 make Dets table Name usable to qlc.
1016 When there are only simple restrictions on the key position, qlc
1018 uses dets:lookup/2 to look up the keys. When that is not possi‐
1019 ble, the whole table is traversed. Option traverse determines
1020 how this is done:
1021 * first_next - The table is traversed one key at a time by
1023 calling dets:first/1 and dets:next/2.
1024 * select - The table is traversed by calling dets:select/3 and
1026 dets:select/1. Option n_objects determines the number of
1027 objects returned (the third argument of select/3). The match
1028 specification (the second argument of select/3) is assembled
1029 by qlc:
1030 * Simple filters are translated into equivalent match speci‐
1032 fications.
1033 * More complicated filters must be applied to all objects
1035 returned by select/3 given a match specification that
1036 matches all objects.
1037 * {select, match_spec()} - As for select, the table is tra‐
1039 versed by calling dets:select/3 and dets:select/1. The dif‐
1040 ference is that the match specification is specified explic‐
1041 itly. This is how to state match specifications that cannot
1042 easily be expressed within the syntax provided by qlc.
1043 The following example uses an explicit match specification to
1045 traverse the table:
1046 1> dets:open_file(t, []),
1048 ok = dets:insert(t, [{1,a},{2,b},{3,c},{4,d}]),
1049 MS = ets:fun2ms(fun({X,Y}) when (X > 1) or (X < 5) -> {Y} end),
1050 QH1 = dets:table(t, [{traverse, {select, MS}}]).
1051 An example with implicit match specification:
1053 2> QH2 = qlc:q([{Y} || {X,Y} <- dets:table(t), (X > 1) or (X < 5)]).
1055 The latter example is equivalent to the former, which can be
1057 verified using function qlc:info/1:
1058 3> qlc:info(QH1) =:= qlc:info(QH2).
1060 true
1061 qlc:info/1 returns information about a query handle. In this
1063 case identical information is returned for the two query han‐
1064 dles.
1065 to_ets(Name, EtsTab) -> EtsTab | {error, Reason}
1067 Types:
1069 Name = tab_name()
1071 EtsTab = ets:tab()
1072 Reason = term()
1073 Inserts the objects of the Dets table Name into the ETS table
1075 EtsTab. The order in which the objects are inserted is not spec‐
1076 ified. The existing objects of the ETS table are kept unless
1077 overwritten.
1078 traverse(Name, Fun) -> Return | {error, Reason}
1080 Types:
1082 Name = tab_name()
1084 Fun = fun((Object) -> FunReturn)
1085 Object = object()
1086 FunReturn =
1087 continue | {continue, Val} | {done, Value} | OtherValue
1088 Return = [term()] | OtherValue
1089 Val = Value = OtherValue = Reason = term()
1090 Applies Fun to each object stored in table Name in some unspeci‐
1092 fied order. Different actions are taken depending on the return
1093 value of Fun. The following Fun return values are allowed:
1094 continue:
1096 Continue to perform the traversal. For example, the follow‐
1097 ing function can be used to print the contents of a table:
1098 fun(X) -> io:format("~p~n", [X]), continue end.
1100 {continue, Val}:
1102 Continue the traversal and accumulate Val. The following
1103 function is supplied to collect all objects of a table in a
1104 list:
1105 fun(X) -> {continue, X} end.
1107 {done, Value}:
1109 Terminate the traversal and return [Value | Acc].
1110 Any other value OtherValue returned by Fun terminates the tra‐
1112 versal and is returned immediately.
1113 update_counter(Name, Key, Increment) -> Result
1115 Types:
1117 Name = tab_name()
1119 Key = term()
1120 Increment = {Pos, Incr} | Incr
1121 Pos = Incr = Result = integer()
1122 Updates the object with key Key stored in table Name of type set
1124 by adding Incr to the element at the Pos:th position. The new
1125 counter value is returned. If no position is specified, the ele‐
1126 ment directly following the key is updated.
1127 This functions provides a way of updating a counter, without
1129 having to look up an object, update the object by incrementing
1130 an element, and insert the resulting object into the table
1131 again.
1132
1134 ets(3), mnesia(3), qlc(3)
1135Ericsson AB stdlib 3.4.5.1 dets(3)