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 | auto_save | bchunk_format | hash | file_size |
289 filename | keypos | memory | no_keys | no_objects |
290 no_slots |
291 owner | ram_file | safe_fixed | safe_fixed_monotonic_time
292 |
293 size | type
294 Value = term()
295 Returns the information associated with Item for table Name. In
297 addition to the {Item, Value} pairs defined for info/1, the fol‐
298 lowing items are allowed:
299 * {access, access()} - The access mode.
301 * {auto_save, auto_save()} - The autosave interval.
303 * {bchunk_format, binary()} - An opaque binary describing the
305 format of the objects returned by bchunk/2. The binary can
306 be used as argument to is_compatible_chunk_format/2.
307 * {hash, Hash} - Describes which BIF is used to calculate the
309 hash values of the objects stored in the Dets table. Possi‐
310 ble values of Hash:
311 * phash - Implies that the erlang:phash/2 BIF is used.
313 * phash2 - Implies that the erlang:phash2/1 BIF is used.
315 * {memory, integer() >= 0} - The file size, in bytes. The same
317 value is associated with item file_size.
318 * {no_keys, integer >= 0()} - The number of different keys
320 stored in the table.
321 * {no_objects, integer >= 0()} - The number of objects stored
323 in the table.
324 * {no_slots, {Min, Used, Max}} - The number of slots of the
326 table. Min is the minimum number of slots, Used is the num‐
327 ber of currently used slots, and Max is the maximum number
328 of slots.
329 * {owner, pid()} - The pid of the process that handles
331 requests to the Dets table.
332 * {ram_file, boolean()} - Whether the table is kept in RAM.
334 * {safe_fixed_monotonic_time, SafeFixed} - If the table is
336 fixed, SafeFixed is a tuple {FixedAtTime, [{Pid,RefCount}]}.
337 FixedAtTime is the time when the table was first fixed, and
338 Pid is the pid of the process that fixes the table RefCount
339 times. There can be any number of processes in the list. If
340 the table is not fixed, SafeFixed is the atom false.
341 FixedAtTime corresponds to the result returned by
343 erlang:monotonic_time/0 at the time of fixation. The use of
344 safe_fixed_monotonic_time is time warp safe.
345 * {safe_fixed, SafeFixed} - The same as {safe_fixed_mono‐
347 tonic_time, SafeFixed} except the format and value of Fixe‐
348 dAtTime.
349 FixedAtTime corresponds to the result returned by
351 erlang:timestamp/0 at the time of fixation. Notice that when
352 the system uses single or multi time warp modes, this can
353 produce strange results. This is because the use of
354 safe_fixed is not time warp safe. Time warp safe code must
355 use safe_fixed_monotonic_time instead.
356 init_table(Name, InitFun) -> ok | {error, Reason}
358 init_table(Name, InitFun, Options) -> ok | {error, Reason}
360 Types:
362 Name = tab_name()
364 InitFun = fun((Arg) -> Res)
365 Arg = read | close
366 Res =
367 end_of_input |
368 {[object()], InitFun} |
369 {Data, InitFun} |
370 term()
371 Options = Option | [Option]
372 Option = {min_no_slots, no_slots()} | {format, term | bchunk}
373 Reason = term()
374 Data = binary() | tuple()
375 Replaces the existing objects of table Name with objects created
377 by calling the input function InitFun, see below. The reason for
378 using this function rather than calling insert/2 is that of
379 efficiency. Notice that the input functions are called by the
380 process that handles requests to the Dets table, not by the
381 calling process.
382 When called with argument read, function InitFun is assumed to
384 return end_of_input when there is no more input, or {Objects,
385 Fun}, where Objects is a list of objects and Fun is a new input
386 function. Any other value Value is returned as an error {error,
387 {init_fun, Value}}. Each input function is called exactly once,
388 and if an error occurs, the last function is called with argu‐
389 ment close, the reply of which is ignored.
390 If the table type is set and more than one object exists with a
392 given key, one of the objects is chosen. This is not necessarily
393 the last object with the given key in the sequence of objects
394 returned by the input functions. Avoid duplicate keys, otherwise
395 the file becomes unnecessarily fragmented. This holds also for
396 duplicated objects stored in tables of type bag.
397 It is important that the table has a sufficient number of slots
399 for the objects. If not, the hash list starts to grow when
400 init_table/2 returns, which significantly slows down access to
401 the table for a period of time. The minimum number of slots is
402 set by the open_file/2 option min_no_slots and returned by the
403 info/2 item no_slots. See also option min_no_slots below.
404 Argument Options is a list of {Key, Val} tuples, where the fol‐
406 lowing values are allowed:
407 * {min_no_slots, no_slots()} - Specifies the estimated number
409 of different keys to be stored in the table. The open_file/2
410 option with the same name is ignored, unless the table is
411 created, in which case performance can be enhanced by sup‐
412 plying an estimate when initializing the table.
413 * {format, Format} - Specifies the format of the objects
415 returned by function InitFun. If Format is term (the
416 default), InitFun is assumed to return a list of tuples. If
417 Format is bchunk, InitFun is assumed to return Data as
418 returned by bchunk/2. This option overrides option
419 min_no_slots.
420 insert(Name, Objects) -> ok | {error, Reason}
422 Types:
424 Name = tab_name()
426 Objects = object() | [object()]
427 Reason = term()
428 Inserts one or more objects into the table Name. If there
430 already exists an object with a key matching the key of some of
431 the given objects and the table type is set, the old object will
432 be replaced.
433 insert_new(Name, Objects) -> boolean() | {error, Reason}
435 Types:
437 Name = tab_name()
439 Objects = object() | [object()]
440 Reason = term()
441 Inserts one or more objects into table Name. If there already
443 exists some object with a key matching the key of any of the
444 specified objects, the table is not updated and false is
445 returned. Otherwise the objects are inserted and true returned.
446 is_compatible_bchunk_format(Name, BchunkFormat) -> boolean()
448 Types:
450 Name = tab_name()
452 BchunkFormat = binary()
453 Returns true if it would be possible to initialize table Name,
455 using init_table/3 with option {format, bchunk}, with objects
456 read with bchunk/2 from some table T, such that calling info(T,
457 bchunk_format) returns BchunkFormat.
458 is_dets_file(Filename) -> boolean() | {error, Reason}
460 Types:
462 Filename = file:name()
464 Reason = term()
465 Returns true if file Filename is a Dets table, otherwise false.
467 lookup(Name, Key) -> Objects | {error, Reason}
469 Types:
471 Name = tab_name()
473 Key = term()
474 Objects = [object()]
475 Reason = term()
476 Returns a list of all objects with key Key stored in table Name,
478 for example:
479 2> dets:open_file(abc, [{type, bag}]).
481 {ok,abc}
482 3> dets:insert(abc, {1,2,3}).
483 ok
484 4> dets:insert(abc, {1,3,4}).
485 ok
486 5> dets:lookup(abc, 1).
487 [{1,2,3},{1,3,4}]
488 If the table type is set, the function returns either the empty
490 list or a list with one object, as there cannot be more than one
491 object with a given key. If the table type is bag or dupli‐
492 cate_bag, the function returns a list of arbitrary length.
493 Notice that the order of objects returned is unspecified. In
495 particular, the order in which objects were inserted is not
496 reflected.
497 match(Continuation) ->
499 {[Match], Continuation2} |
500 '$end_of_table' |
501 {error, Reason}
502 Types:
504 Continuation = Continuation2 = bindings_cont()
506 Match = [term()]
507 Reason = term()
508 Matches some objects stored in a table and returns a non-empty
510 list of the bindings matching a specified pattern in some
511 unspecified order. The table, the pattern, and the number of
512 objects that are matched are all defined by Continuation, which
513 has been returned by a previous call to match/1 or match/3.
514 When all table objects are matched, '$end_of_table' is returned.
516 match(Name, Pattern) -> [Match] | {error, Reason}
518 Types:
520 Name = tab_name()
522 Pattern = pattern()
523 Match = [term()]
524 Reason = term()
525 Returns for each object of table Name that matches Pattern a
527 list of bindings in some unspecified order. For a description of
528 patterns, see ets:match/2. If the keypos'th element of Pattern
529 is unbound, all table objects are matched. If the keypos'th ele‐
530 ment is bound, only the objects with the correct key are
531 matched.
532 match(Name, Pattern, N) ->
534 {[Match], Continuation} |
535 '$end_of_table' |
536 {error, Reason}
537 Types:
539 Name = tab_name()
541 Pattern = pattern()
542 N = default | integer() >= 0
543 Continuation = bindings_cont()
544 Match = [term()]
545 Reason = term()
546 Matches some or all objects of table Name and returns a non-
548 empty list of the bindings that match Pattern in some unspeci‐
549 fied order. For a description of patterns, see ets:match/2.
550 A tuple of the bindings and a continuation is returned, unless
552 the table is empty, in which case '$end_of_table' is returned.
553 The continuation is to be used when matching further objects by
554 calling match/1.
555 If the keypos'th element of Pattern is bound, all table objects
557 are matched. If the keypos'th element is unbound, all table
558 objects are matched, N objects at a time, until at least one
559 object matches or the end of the table is reached. The default,
560 indicated by giving N the value default, is to let the number of
561 objects vary depending on the sizes of the objects. All objects
562 with the same key are always matched at the same time, which
563 implies that more than N objects can sometimes be matched.
564 The table is always to be protected using safe_fixtable/2 before
566 calling match/3, otherwise errors can occur when calling
567 match/1.
568 match_delete(Name, Pattern) -> ok | {error, Reason}
570 Types:
572 Name = tab_name()
574 Pattern = pattern()
575 Reason = term()
576 Deletes all objects that match Pattern from table Name. For a
578 description of patterns, see ets:match/2.
579 If the keypos'th element of Pattern is bound, only the objects
581 with the correct key are matched.
582 match_object(Continuation) ->
584 {Objects, Continuation2} |
585 '$end_of_table' |
586 {error, Reason}
587 Types:
589 Continuation = Continuation2 = object_cont()
591 Objects = [object()]
592 Reason = term()
593 Returns a non-empty list of some objects stored in a table that
595 match a given pattern in some unspecified order. The table, the
596 pattern, and the number of objects that are matched are all
597 defined by Continuation, which has been returned by a previous
598 call to match_object/1 or match_object/3.
599 When all table objects are matched, '$end_of_table' is returned.
601 match_object(Name, Pattern) -> Objects | {error, Reason}
603 Types:
605 Name = tab_name()
607 Pattern = pattern()
608 Objects = [object()]
609 Reason = term()
610 Returns a list of all objects of table Name that match Pattern
612 in some unspecified order. For a description of patterns, see
613 ets:match/2.
614 If the keypos'th element of Pattern is unbound, all table
616 objects are matched. If the keypos'th element of Pattern is
617 bound, only the objects with the correct key are matched.
618 Using the match_object functions for traversing all table
620 objects is more efficient than calling first/1 and next/2 or
621 slot/2.
622 match_object(Name, Pattern, N) ->
624 {Objects, Continuation} |
625 '$end_of_table' |
626 {error, Reason}
627 Types:
629 Name = tab_name()
631 Pattern = pattern()
632 N = default | integer() >= 0
633 Continuation = object_cont()
634 Objects = [object()]
635 Reason = term()
636 Matches some or all objects stored in table Name and returns a
638 non-empty list of the objects that match Pattern in some unspec‐
639 ified order. For a description of patterns, see ets:match/2.
640 A list of objects and a continuation is returned, unless the ta‐
642 ble is empty, in which case '$end_of_table' is returned. The
643 continuation is to be used when matching further objects by
644 calling match_object/1.
645 If the keypos'th element of Pattern is bound, all table objects
647 are matched. If the keypos'th element is unbound, all table
648 objects are matched, N objects at a time, until at least one
649 object matches or the end of the table is reached. The default,
650 indicated by giving N the value default, is to let the number of
651 objects vary depending on the sizes of the objects. All matching
652 objects with the same key are always returned in the same reply,
653 which implies that more than N objects can sometimes be
654 returned.
655 The table is always to be protected using safe_fixtable/2 before
657 calling match_object/3, otherwise errors can occur when calling
658 match_object/1.
659 member(Name, Key) -> boolean() | {error, Reason}
661 Types:
663 Name = tab_name()
665 Key = Reason = term()
666 Works like lookup/2, but does not return the objects. Returns
668 true if one or more table elements has key Key, otherwise false.
669 next(Name, Key1) -> Key2 | '$end_of_table'
671 Types:
673 Name = tab_name()
675 Key1 = Key2 = term()
676 Returns either the key following Key1 in table Name according to
678 the internal order of the table, or '$end_of_table' if there is
679 no next key.
680 If an error occurs, the process is exited with an error tuple
682 {error, Reason}.
683 To find the first key in the table, use first/1.
685 open_file(Filename) -> {ok, Reference} | {error, Reason}
687 Types:
689 Filename = file:name()
691 Reference = reference()
692 Reason = term()
693 Opens an existing table. If the table is not properly closed, it
695 is repaired. The returned reference is to be used as the table
696 name. This function is most useful for debugging purposes.
697 open_file(Name, Args) -> {ok, Name} | {error, Reason}
699 Types:
701 Name = tab_name()
703 Args = [OpenArg]
704 OpenArg =
705 {access, access()} |
706 {auto_save, auto_save()} |
707 {estimated_no_objects, integer() >= 0} |
708 {file, file:name()} |
709 {max_no_slots, no_slots()} |
710 {min_no_slots, no_slots()} |
711 {keypos, keypos()} |
712 {ram_file, boolean()} |
713 {repair, boolean() | force} |
714 {type, type()}
715 Reason = term()
716 Opens a table. An empty Dets table is created if no file exists.
718 The atom Name is the table name. The table name must be provided
720 in all subsequent operations on the table. The name can be used
721 by other processes as well, and many processes can share one ta‐
722 ble.
723 If two processes open the same table by giving the same name and
725 arguments, the table has two users. If one user closes the ta‐
726 ble, it remains open until the second user closes it.
727 Argument Args is a list of {Key, Val} tuples, where the follow‐
729 ing values are allowed:
730 * {access, access()} - Existing tables can be opened in read-
732 only mode. A table that is opened in read-only mode is not
733 subjected to the automatic file reparation algorithm if it
734 is later opened after a crash. Defaults to read_write.
735 * {auto_save, auto_save()} - The autosave interval. If the
737 interval is an integer Time, the table is flushed to disk
738 whenever it is not accessed for Time milliseconds. A table
739 that has been flushed requires no reparation when reopened
740 after an uncontrolled emulator halt. If the interval is the
741 atom infinity, autosave is disabled. Defaults to 180000 (3
742 minutes).
743 * {estimated_no_objects, no_slots()} - Equivalent to option
745 min_no_slots.
746 * {file, file:name()} - The name of the file to be opened.
748 Defaults to the table name.
749 * {max_no_slots, no_slots()} - The maximum number of slots to
751 be used. Defaults to 32 M, which is the maximal value.
752 Notice that a higher value can increase the table fragmenta‐
753 tion, and a smaller value can decrease the fragmentation, at
754 the expense of execution time.
755 * {min_no_slots, no_slots()} - Application performance can be
757 enhanced with this flag by specifying, when the table is
758 created, the estimated number of different keys to be stored
759 in the table. Defaults to 256, which is the minimum value.
760 * {keypos, keypos()} - The position of the element of each
762 object to be used as key. Defaults to 1. The ability to
763 explicitly state the key position is most convenient when we
764 want to store Erlang records in which the first position of
765 the record is the name of the record type.
766 * {ram_file, boolean()} - Whether the table is to be kept in
768 RAM. Keeping the table in RAM can sound like an anomaly, but
769 can enhance the performance of applications that open a ta‐
770 ble, insert a set of objects, and then close the table. When
771 the table is closed, its contents are written to the disk
772 file. Defaults to false.
773 * {repair, Value} - Value can be either a boolean() or the
775 atom force. The flag specifies if the Dets server is to
776 invoke the automatic file reparation algorithm. Defaults to
777 true. If false is specified, no attempt is made to repair
778 the file, and {error, {needs_repair, FileName}} is returned
779 if the table must be repaired.
780 Value force means that a reparation is made even if the ta‐
782 ble is properly closed. This is a seldom needed option.
783 Option repair is ignored if the table is already open.
785 * {type, type()} - The table type. Defaults to set.
787 pid2name(Pid) -> {ok, Name} | undefined
789 Types:
791 Pid = pid()
793 Name = tab_name()
794 Returns the table name given the pid of a process that handles
796 requests to a table, or undefined if there is no such table.
797 This function is meant to be used for debugging only.
799 repair_continuation(Continuation, MatchSpec) -> Continuation2
801 Types:
803 Continuation = Continuation2 = select_cont()
805 MatchSpec = match_spec()
806 This function can be used to restore an opaque continuation
808 returned by select/3 or select/1 if the continuation has passed
809 through external term format (been sent between nodes or stored
810 on disk).
811 The reason for this function is that continuation terms contain
813 compiled match specifications and therefore are invalidated if
814 converted to external term format. Given that the original match
815 specification is kept intact, the continuation can be restored,
816 meaning it can once again be used in subsequent select/1 calls
817 even though it has been stored on disk or on another node.
818 For more information and examples, see the ets(3) module.
820 Note:
822 This function is rarely needed in application code. It is used
823 by application Mnesia to provide distributed select/3 and
824 select/1 sequences. A normal application would either use Mnesia
825 or keep the continuation from being converted to external for‐
826 mat.
827 The reason for not having an external representation of compiled
829 match specifications is performance. It can be subject to change
830 in future releases, while this interface remains for backward
831 compatibility.
832 safe_fixtable(Name, Fix) -> ok
835 Types:
837 Name = tab_name()
839 Fix = boolean()
840 If Fix is true, table Name is fixed (once more) by the calling
842 process, otherwise the table is released. The table is also
843 released when a fixing process terminates.
844 If many processes fix a table, the table remains fixed until all
846 processes have released it or terminated. A reference counter is
847 kept on a per process basis, and N consecutive fixes require N
848 releases to release the table.
849 It is not guaranteed that calls to first/1, next/2, or select
851 and match functions work as expected even if the table is fixed;
852 the limited support for concurrency provided by the ets(3) mod‐
853 ule is not yet provided by Dets. Fixing a table currently only
854 disables resizing of the hash list of the table.
855 If objects have been added while the table was fixed, the hash
857 list starts to grow when the table is released, which signifi‐
858 cantly slows down access to the table for a period of time.
859 select(Continuation) ->
861 {Selection, Continuation2} |
862 '$end_of_table' |
863 {error, Reason}
864 Types:
866 Continuation = Continuation2 = select_cont()
868 Selection = [term()]
869 Reason = term()
870 Applies a match specification to some objects stored in a table
872 and returns a non-empty list of the results. The table, the
873 match specification, and the number of objects that are matched
874 are all defined by Continuation, which is returned by a previous
875 call to select/1 or select/3.
876 When all objects of the table have been matched, '$end_of_table'
878 is returned.
879 select(Name, MatchSpec) -> Selection | {error, Reason}
881 Types:
883 Name = tab_name()
885 MatchSpec = match_spec()
886 Selection = [term()]
887 Reason = term()
888 Returns the results of applying match specification MatchSpec to
890 all or some objects stored in table Name. The order of the
891 objects is not specified. For a description of match specifica‐
892 tions, see the ERTS User's Guide.
893 If the keypos'th element of MatchSpec is unbound, the match
895 specification is applied to all objects of the table. If the
896 keypos'th element is bound, the match specification is applied
897 to the objects with the correct key(s) only.
898 Using the select functions for traversing all objects of a table
900 is more efficient than calling first/1 and next/2 or slot/2.
901 select(Name, MatchSpec, N) ->
903 {Selection, Continuation} |
904 '$end_of_table' |
905 {error, Reason}
906 Types:
908 Name = tab_name()
910 MatchSpec = match_spec()
911 N = default | integer() >= 0
912 Continuation = select_cont()
913 Selection = [term()]
914 Reason = term()
915 Returns the results of applying match specification MatchSpec to
917 some or all objects stored in table Name. The order of the
918 objects is not specified. For a description of match specifica‐
919 tions, see the ERTS User's Guide.
920 A tuple of the results of applying the match specification and a
922 continuation is returned, unless the table is empty, in which
923 case '$end_of_table' is returned. The continuation is to be used
924 when matching more objects by calling select/1.
925 If the keypos'th element of MatchSpec is bound, the match speci‐
927 fication is applied to all objects of the table with the correct
928 key(s). If the keypos'th element of MatchSpec is unbound, the
929 match specification is applied to all objects of the table, N
930 objects at a time, until at least one object matches or the end
931 of the table is reached. The default, indicated by giving N the
932 value default, is to let the number of objects vary depending on
933 the sizes of the objects. All objects with the same key are
934 always handled at the same time, which implies that the match
935 specification can be applied to more than N objects.
936 The table is always to be protected using safe_fixtable/2 before
938 calling select/3, otherwise errors can occur when calling
939 select/1.
940 select_delete(Name, MatchSpec) -> N | {error, Reason}
942 Types:
944 Name = tab_name()
946 MatchSpec = match_spec()
947 N = integer() >= 0
948 Reason = term()
949 Deletes each object from table Name such that applying match
951 specification MatchSpec to the object returns value true. For a
952 description of match specifications, see the ERTS User's Guide.
953 Returns the number of deleted objects.
954 If the keypos'th element of MatchSpec is bound, the match speci‐
956 fication is applied to the objects with the correct key(s) only.
957 slot(Name, I) -> '$end_of_table' | Objects | {error, Reason}
959 Types:
961 Name = tab_name()
963 I = integer() >= 0
964 Objects = [object()]
965 Reason = term()
966 The objects of a table are distributed among slots, starting
968 with slot 0 and ending with slot n. Returns the list of objects
969 associated with slot I. If I > n, '$end_of_table' is returned.
970 sync(Name) -> ok | {error, Reason}
972 Types:
974 Name = tab_name()
976 Reason = term()
977 Ensures that all updates made to table Name are written to disk.
979 This also applies to tables that have been opened with flag
980 ram_file set to true. In this case, the contents of the RAM file
981 are flushed to disk.
982 Notice that the space management data structures kept in RAM,
984 the buddy system, is also written to the disk. This can take
985 some time if the table is fragmented.
986 table(Name) -> QueryHandle
988 table(Name, Options) -> QueryHandle
990 Types:
992 Name = tab_name()
994 Options = Option | [Option]
995 Option = {n_objects, Limit} | {traverse, TraverseMethod}
996 Limit = default | integer() >= 1
997 TraverseMethod = first_next | select | {select, match_spec()}
998 QueryHandle = qlc:query_handle()
999 Returns a Query List Comprehension (QLC) query handle. The
1001 qlc(3) module provides a query language aimed mainly for Mnesia,
1002 but ETS tables, Dets tables, and lists are also recognized by
1003 qlc as sources of data. Calling dets:table/1,2 is the means to
1004 make Dets table Name usable to qlc.
1005 When there are only simple restrictions on the key position, qlc
1007 uses dets:lookup/2 to look up the keys. When that is not possi‐
1008 ble, the whole table is traversed. Option traverse determines
1009 how this is done:
1010 * first_next - The table is traversed one key at a time by
1012 calling dets:first/1 and dets:next/2.
1013 * select - The table is traversed by calling dets:select/3 and
1015 dets:select/1. Option n_objects determines the number of
1016 objects returned (the third argument of select/3). The match
1017 specification (the second argument of select/3) is assembled
1018 by qlc:
1019 * Simple filters are translated into equivalent match speci‐
1021 fications.
1022 * More complicated filters must be applied to all objects
1024 returned by select/3 given a match specification that
1025 matches all objects.
1026 * {select, match_spec()} - As for select, the table is tra‐
1028 versed by calling dets:select/3 and dets:select/1. The dif‐
1029 ference is that the match specification is specified explic‐
1030 itly. This is how to state match specifications that cannot
1031 easily be expressed within the syntax provided by qlc.
1032 The following example uses an explicit match specification to
1034 traverse the table:
1035 1> dets:open_file(t, []),
1037 ok = dets:insert(t, [{1,a},{2,b},{3,c},{4,d}]),
1038 MS = ets:fun2ms(fun({X,Y}) when (X > 1) or (X < 5) -> {Y} end),
1039 QH1 = dets:table(t, [{traverse, {select, MS}}]).
1040 An example with implicit match specification:
1042 2> QH2 = qlc:q([{Y} || {X,Y} <- dets:table(t), (X > 1) or (X < 5)]).
1044 The latter example is equivalent to the former, which can be
1046 verified using function qlc:info/1:
1047 3> qlc:info(QH1) =:= qlc:info(QH2).
1049 true
1050 qlc:info/1 returns information about a query handle. In this
1052 case identical information is returned for the two query han‐
1053 dles.
1054 to_ets(Name, EtsTab) -> EtsTab | {error, Reason}
1056 Types:
1058 Name = tab_name()
1060 EtsTab = ets:tab()
1061 Reason = term()
1062 Inserts the objects of the Dets table Name into the ETS table
1064 EtsTab. The order in which the objects are inserted is not spec‐
1065 ified. The existing objects of the ETS table are kept unless
1066 overwritten.
1067 traverse(Name, Fun) -> Return | {error, Reason}
1069 Types:
1071 Name = tab_name()
1073 Fun = fun((Object) -> FunReturn)
1074 Object = object()
1075 FunReturn =
1076 continue | {continue, Val} | {done, Value} | OtherValue
1077 Return = [term()] | OtherValue
1078 Val = Value = OtherValue = Reason = term()
1079 Applies Fun to each object stored in table Name in some unspeci‐
1081 fied order. Different actions are taken depending on the return
1082 value of Fun. The following Fun return values are allowed:
1083 continue:
1085 Continue to perform the traversal. For example, the follow‐
1086 ing function can be used to print the contents of a table:
1087 fun(X) -> io:format("~p~n", [X]), continue end.
1089 {continue, Val}:
1091 Continue the traversal and accumulate Val. The following
1092 function is supplied to collect all objects of a table in a
1093 list:
1094 fun(X) -> {continue, X} end.
1096 {done, Value}:
1098 Terminate the traversal and return [Value | Acc].
1099 Any other value OtherValue returned by Fun terminates the tra‐
1101 versal and is returned immediately.
1102 update_counter(Name, Key, Increment) -> Result
1104 Types:
1106 Name = tab_name()
1108 Key = term()
1109 Increment = {Pos, Incr} | Incr
1110 Pos = Incr = Result = integer()
1111 Updates the object with key Key stored in table Name of type set
1113 by adding Incr to the element at the Pos:th position. The new
1114 counter value is returned. If no position is specified, the ele‐
1115 ment directly following the key is updated.
1116 This functions provides a way of updating a counter, without
1118 having to look up an object, update the object by incrementing
1119 an element, and insert the resulting object into the table
1120 again.
1121
1123 ets(3), mnesia(3), qlc(3)
1124Ericsson AB stdlib 3.12.1 dets(3)