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 im‐
57 plementation 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 se‐
64 quence 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 Er‐
66 lang/OTP. Until then, the Mnesia application (or some user-implemented
67 method for locking) must be used to implement safe concurrency. Cur‐
68 rently, no Erlang/OTP library has support for ordered disk-based term
69 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 al‐
163 lowed 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 in‐
209 ternal 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 se‐
224 lect 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 ob‐
251 jects of the ETS table EtsTab. The objects are inserted in un‐
252 specified order. As ets:safe_fixtable/2 is called, the ETS table
253 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 re‐
331 quests 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 er‐
343 lang: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 er‐
351 lang: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 ef‐
379 ficiency. 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 re‐
415 turned by function InitFun. If Format is term (the default),
416 InitFun is assumed to return a list of tuples. If Format is
417 bchunk, InitFun is assumed to return Data as returned by
418 bchunk/2. This option overrides option min_no_slots.
419 insert(Name, Objects) -> ok | {error, Reason}
421 Types:
423 Name = tab_name()
425 Objects = object() | [object()]
426 Reason = term()
427 Inserts one or more objects into the table Name. If there al‐
429 ready exists an object with a key matching the key of some of
430 the given objects and the table type is set, the old object will
431 be replaced.
432 insert_new(Name, Objects) -> boolean() | {error, Reason}
434 Types:
436 Name = tab_name()
438 Objects = object() | [object()]
439 Reason = term()
440 Inserts one or more objects into table Name. If there already
442 exists some object with a key matching the key of any of the
443 specified objects, the table is not updated and false is re‐
444 turned. Otherwise the objects are inserted and true returned.
445 is_compatible_bchunk_format(Name, BchunkFormat) -> boolean()
447 Types:
449 Name = tab_name()
451 BchunkFormat = binary()
452 Returns true if it would be possible to initialize table Name,
454 using init_table/3 with option {format, bchunk}, with objects
455 read with bchunk/2 from some table T, such that calling info(T,
456 bchunk_format) returns BchunkFormat.
457 is_dets_file(Filename) -> boolean() | {error, Reason}
459 Types:
461 Filename = file:name()
463 Reason = term()
464 Returns true if file Filename is a Dets table, otherwise false.
466 lookup(Name, Key) -> Objects | {error, Reason}
468 Types:
470 Name = tab_name()
472 Key = term()
473 Objects = [object()]
474 Reason = term()
475 Returns a list of all objects with key Key stored in table Name,
477 for example:
478 2> dets:open_file(abc, [{type, bag}]).
480 {ok,abc}
481 3> dets:insert(abc, {1,2,3}).
482 ok
483 4> dets:insert(abc, {1,3,4}).
484 ok
485 5> dets:lookup(abc, 1).
486 [{1,2,3},{1,3,4}]
487 If the table type is set, the function returns either the empty
489 list or a list with one object, as there cannot be more than one
490 object with a given key. If the table type is bag or dupli‐
491 cate_bag, the function returns a list of arbitrary length.
492 Notice that the order of objects returned is unspecified. In
494 particular, the order in which objects were inserted is not re‐
495 flected.
496 match(Continuation) ->
498 {[Match], Continuation2} |
499 '$end_of_table' |
500 {error, Reason}
501 Types:
503 Continuation = Continuation2 = bindings_cont()
505 Match = [term()]
506 Reason = term()
507 Matches some objects stored in a table and returns a non-empty
509 list of the bindings matching a specified pattern in some un‐
510 specified order. The table, the pattern, and the number of ob‐
511 jects that are matched are all defined by Continuation, which
512 has been returned by a previous call to match/1 or match/3.
513 When all table objects are matched, '$end_of_table' is returned.
515 match(Name, Pattern) -> [Match] | {error, Reason}
517 Types:
519 Name = tab_name()
521 Pattern = pattern()
522 Match = [term()]
523 Reason = term()
524 Returns for each object of table Name that matches Pattern a
526 list of bindings in some unspecified order. For a description of
527 patterns, see ets:match/2. If the keypos'th element of Pattern
528 is unbound, all table objects are matched. If the keypos'th ele‐
529 ment is bound, only the objects with the correct key are
530 matched.
531 match(Name, Pattern, N) ->
533 {[Match], Continuation} |
534 '$end_of_table' |
535 {error, Reason}
536 Types:
538 Name = tab_name()
540 Pattern = pattern()
541 N = default | integer() >= 0
542 Continuation = bindings_cont()
543 Match = [term()]
544 Reason = term()
545 Matches some or all objects of table Name and returns a non-
547 empty list of the bindings that match Pattern in some unspeci‐
548 fied order. For a description of patterns, see ets:match/2.
549 A tuple of the bindings and a continuation is returned, unless
551 the table is empty, in which case '$end_of_table' is returned.
552 The continuation is to be used when matching further objects by
553 calling match/1.
554 If the keypos'th element of Pattern is bound, all table objects
556 are matched. If the keypos'th element is unbound, all table ob‐
557 jects are matched, N objects at a time, until at least one ob‐
558 ject matches or the end of the table is reached. The default,
559 indicated by giving N the value default, is to let the number of
560 objects vary depending on the sizes of the objects. All objects
561 with the same key are always matched at the same time, which im‐
562 plies that more than N objects can sometimes be matched.
563 The table is always to be protected using safe_fixtable/2 before
565 calling match/3, otherwise errors can occur when calling
566 match/1.
567 match_delete(Name, Pattern) -> ok | {error, Reason}
569 Types:
571 Name = tab_name()
573 Pattern = pattern()
574 Reason = term()
575 Deletes all objects that match Pattern from table Name. For a
577 description of patterns, see ets:match/2.
578 If the keypos'th element of Pattern is bound, only the objects
580 with the correct key are matched.
581 match_object(Continuation) ->
583 {Objects, Continuation2} |
584 '$end_of_table' |
585 {error, Reason}
586 Types:
588 Continuation = Continuation2 = object_cont()
590 Objects = [object()]
591 Reason = term()
592 Returns a non-empty list of some objects stored in a table that
594 match a given pattern in some unspecified order. The table, the
595 pattern, and the number of objects that are matched are all de‐
596 fined by Continuation, which has been returned by a previous
597 call to match_object/1 or match_object/3.
598 When all table objects are matched, '$end_of_table' is returned.
600 match_object(Name, Pattern) -> Objects | {error, Reason}
602 Types:
604 Name = tab_name()
606 Pattern = pattern()
607 Objects = [object()]
608 Reason = term()
609 Returns a list of all objects of table Name that match Pattern
611 in some unspecified order. For a description of patterns, see
612 ets:match/2.
613 If the keypos'th element of Pattern is unbound, all table ob‐
615 jects are matched. If the keypos'th element of Pattern is bound,
616 only the objects with the correct key are matched.
617 Using the match_object functions for traversing all table ob‐
619 jects is more efficient than calling first/1 and next/2 or
620 slot/2.
621 match_object(Name, Pattern, N) ->
623 {Objects, Continuation} |
624 '$end_of_table' |
625 {error, Reason}
626 Types:
628 Name = tab_name()
630 Pattern = pattern()
631 N = default | integer() >= 0
632 Continuation = object_cont()
633 Objects = [object()]
634 Reason = term()
635 Matches some or all objects stored in table Name and returns a
637 non-empty list of the objects that match Pattern in some unspec‐
638 ified order. For a description of patterns, see ets:match/2.
639 A list of objects and a continuation is returned, unless the ta‐
641 ble is empty, in which case '$end_of_table' is returned. The
642 continuation is to be used when matching further objects by
643 calling match_object/1.
644 If the keypos'th element of Pattern is bound, all table objects
646 are matched. If the keypos'th element is unbound, all table ob‐
647 jects are matched, N objects at a time, until at least one ob‐
648 ject matches or the end of the table is reached. The default,
649 indicated by giving N the value default, is to let the number of
650 objects vary depending on the sizes of the objects. All matching
651 objects with the same key are always returned in the same reply,
652 which implies that more than N objects can sometimes be re‐
653 turned.
654 The table is always to be protected using safe_fixtable/2 before
656 calling match_object/3, otherwise errors can occur when calling
657 match_object/1.
658 member(Name, Key) -> boolean() | {error, Reason}
660 Types:
662 Name = tab_name()
664 Key = Reason = term()
665 Works like lookup/2, but does not return the objects. Returns
667 true if one or more table elements has key Key, otherwise false.
668 next(Name, Key1) -> Key2 | '$end_of_table'
670 Types:
672 Name = tab_name()
674 Key1 = Key2 = term()
675 Returns either the key following Key1 in table Name according to
677 the internal order of the table, or '$end_of_table' if there is
678 no next key.
679 If an error occurs, the process is exited with an error tuple
681 {error, Reason}.
682 To find the first key in the table, use first/1.
684 open_file(Filename) -> {ok, Reference} | {error, Reason}
686 Types:
688 Filename = file:name()
690 Reference = reference()
691 Reason = term()
692 Opens an existing table. If the table is not properly closed, it
694 is repaired. The returned reference is to be used as the table
695 name. This function is most useful for debugging purposes.
696 open_file(Name, Args) -> {ok, Name} | {error, Reason}
698 Types:
700 Name = tab_name()
702 Args = [OpenArg]
703 OpenArg =
704 {access, access()} |
705 {auto_save, auto_save()} |
706 {estimated_no_objects, integer() >= 0} |
707 {file, file:name()} |
708 {max_no_slots, no_slots()} |
709 {min_no_slots, no_slots()} |
710 {keypos, keypos()} |
711 {ram_file, boolean()} |
712 {repair, boolean() | force} |
713 {type, type()}
714 Reason = term()
715 Opens a table. An empty Dets table is created if no file exists.
717 The atom Name is the table name. The table name must be provided
719 in all subsequent operations on the table. The name can be used
720 by other processes as well, and many processes can share one ta‐
721 ble.
722 If two processes open the same table by giving the same name and
724 arguments, the table has two users. If one user closes the ta‐
725 ble, it remains open until the second user closes it.
726 Argument Args is a list of {Key, Val} tuples, where the follow‐
728 ing values are allowed:
729 * {access, access()} - Existing tables can be opened in read-
731 only mode. A table that is opened in read-only mode is not
732 subjected to the automatic file reparation algorithm if it
733 is later opened after a crash. Defaults to read_write.
734 * {auto_save, auto_save()} - The autosave interval. If the in‐
736 terval is an integer Time, the table is flushed to disk
737 whenever it is not accessed for Time milliseconds. A table
738 that has been flushed requires no reparation when reopened
739 after an uncontrolled emulator halt. If the interval is the
740 atom infinity, autosave is disabled. Defaults to 180000 (3
741 minutes).
742 * {estimated_no_objects, no_slots()} - Equivalent to option
744 min_no_slots.
745 * {file, file:name()} - The name of the file to be opened. De‐
747 faults to the table name.
748 * {max_no_slots, no_slots()} - The maximum number of slots to
750 be used. Defaults to 32 M, which is the maximal value. No‐
751 tice that a higher value can increase the table fragmenta‐
752 tion, and a smaller value can decrease the fragmentation, at
753 the expense of execution time.
754 * {min_no_slots, no_slots()} - Application performance can be
756 enhanced with this flag by specifying, when the table is
757 created, the estimated number of different keys to be stored
758 in the table. Defaults to 256, which is the minimum value.
759 * {keypos, keypos()} - The position of the element of each ob‐
761 ject to be used as key. Defaults to 1. The ability to ex‐
762 plicitly state the key position is most convenient when we
763 want to store Erlang records in which the first position of
764 the record is the name of the record type.
765 * {ram_file, boolean()} - Whether the table is to be kept in
767 RAM. Keeping the table in RAM can sound like an anomaly, but
768 can enhance the performance of applications that open a ta‐
769 ble, insert a set of objects, and then close the table. When
770 the table is closed, its contents are written to the disk
771 file. Defaults to false.
772 * {repair, Value} - Value can be either a boolean() or the
774 atom force. The flag specifies if the Dets server is to in‐
775 voke the automatic file reparation algorithm. Defaults to
776 true. If false is specified, no attempt is made to repair
777 the file, and {error, {needs_repair, FileName}} is returned
778 if the table must be repaired.
779 Value force means that a reparation is made even if the ta‐
781 ble is properly closed. This is a seldom needed option.
782 Option repair is ignored if the table is already open.
784 * {type, type()} - The table type. Defaults to set.
786 pid2name(Pid) -> {ok, Name} | undefined
788 Types:
790 Pid = pid()
792 Name = tab_name()
793 Returns the table name given the pid of a process that handles
795 requests to a table, or undefined if there is no such table.
796 This function is meant to be used for debugging only.
798 repair_continuation(Continuation, MatchSpec) -> Continuation2
800 Types:
802 Continuation = Continuation2 = select_cont()
804 MatchSpec = match_spec()
805 This function can be used to restore an opaque continuation re‐
807 turned by select/3 or select/1 if the continuation has passed
808 through external term format (been sent between nodes or stored
809 on disk).
810 The reason for this function is that continuation terms contain
812 compiled match specifications and therefore are invalidated if
813 converted to external term format. Given that the original match
814 specification is kept intact, the continuation can be restored,
815 meaning it can once again be used in subsequent select/1 calls
816 even though it has been stored on disk or on another node.
817 For more information and examples, see the ets(3) module.
819 Note:
821 This function is rarely needed in application code. It is used
822 by application Mnesia to provide distributed select/3 and se‐
823 lect/1 sequences. A normal application would either use Mnesia
824 or keep the continuation from being converted to external for‐
825 mat.
826 The reason for not having an external representation of compiled
828 match specifications is performance. It can be subject to change
829 in future releases, while this interface remains for backward
830 compatibility.
831 safe_fixtable(Name, Fix) -> ok
834 Types:
836 Name = tab_name()
838 Fix = boolean()
839 If Fix is true, table Name is fixed (once more) by the calling
841 process, otherwise the table is released. The table is also re‐
842 leased when a fixing process terminates.
843 If many processes fix a table, the table remains fixed until all
845 processes have released it or terminated. A reference counter is
846 kept on a per process basis, and N consecutive fixes require N
847 releases to release the table.
848 It is not guaranteed that calls to first/1, next/2, or select
850 and match functions work as expected even if the table is fixed;
851 the limited support for concurrency provided by the ets(3) mod‐
852 ule is not yet provided by Dets. Fixing a table currently only
853 disables resizing of the hash list of the table.
854 If objects have been added while the table was fixed, the hash
856 list starts to grow when the table is released, which signifi‐
857 cantly slows down access to the table for a period of time.
858 select(Continuation) ->
860 {Selection, Continuation2} |
861 '$end_of_table' |
862 {error, Reason}
863 Types:
865 Continuation = Continuation2 = select_cont()
867 Selection = [term()]
868 Reason = term()
869 Applies a match specification to some objects stored in a table
871 and returns a non-empty list of the results. The table, the
872 match specification, and the number of objects that are matched
873 are all defined by Continuation, which is returned by a previous
874 call to select/1 or select/3.
875 When all objects of the table have been matched, '$end_of_table'
877 is returned.
878 select(Name, MatchSpec) -> Selection | {error, Reason}
880 Types:
882 Name = tab_name()
884 MatchSpec = match_spec()
885 Selection = [term()]
886 Reason = term()
887 Returns the results of applying match specification MatchSpec to
889 all or some objects stored in table Name. The order of the ob‐
890 jects is not specified. For a description of match specifica‐
891 tions, see the ERTS User's Guide.
892 If the keypos'th element of MatchSpec is unbound, the match
894 specification is applied to all objects of the table. If the
895 keypos'th element is bound, the match specification is applied
896 to the objects with the correct key(s) only.
897 Using the select functions for traversing all objects of a table
899 is more efficient than calling first/1 and next/2 or slot/2.
900 select(Name, MatchSpec, N) ->
902 {Selection, Continuation} |
903 '$end_of_table' |
904 {error, Reason}
905 Types:
907 Name = tab_name()
909 MatchSpec = match_spec()
910 N = default | integer() >= 0
911 Continuation = select_cont()
912 Selection = [term()]
913 Reason = term()
914 Returns the results of applying match specification MatchSpec to
916 some or all objects stored in table Name. The order of the ob‐
917 jects is not specified. For a description of match specifica‐
918 tions, see the ERTS User's Guide.
919 A tuple of the results of applying the match specification and a
921 continuation is returned, unless the table is empty, in which
922 case '$end_of_table' is returned. The continuation is to be used
923 when matching more objects by calling select/1.
924 If the keypos'th element of MatchSpec is bound, the match speci‐
926 fication is applied to all objects of the table with the correct
927 key(s). If the keypos'th element of MatchSpec is unbound, the
928 match specification is applied to all objects of the table, N
929 objects at a time, until at least one object matches or the end
930 of the table is reached. The default, indicated by giving N the
931 value default, is to let the number of objects vary depending on
932 the sizes of the objects. All objects with the same key are al‐
933 ways handled at the same time, which implies that the match
934 specification can be applied to more than N objects.
935 The table is always to be protected using safe_fixtable/2 before
937 calling select/3, otherwise errors can occur when calling se‐
938 lect/1.
939 select_delete(Name, MatchSpec) -> N | {error, Reason}
941 Types:
943 Name = tab_name()
945 MatchSpec = match_spec()
946 N = integer() >= 0
947 Reason = term()
948 Deletes each object from table Name such that applying match
950 specification MatchSpec to the object returns value true. For a
951 description of match specifications, see the ERTS User's Guide.
952 Returns the number of deleted objects.
953 If the keypos'th element of MatchSpec is bound, the match speci‐
955 fication is applied to the objects with the correct key(s) only.
956 slot(Name, I) -> '$end_of_table' | Objects | {error, Reason}
958 Types:
960 Name = tab_name()
962 I = integer() >= 0
963 Objects = [object()]
964 Reason = term()
965 The objects of a table are distributed among slots, starting
967 with slot 0 and ending with slot n. Returns the list of objects
968 associated with slot I. If I > n, '$end_of_table' is returned.
969 sync(Name) -> ok | {error, Reason}
971 Types:
973 Name = tab_name()
975 Reason = term()
976 Ensures that all updates made to table Name are written to disk.
978 This also applies to tables that have been opened with flag
979 ram_file set to true. In this case, the contents of the RAM file
980 are flushed to disk.
981 Notice that the space management data structures kept in RAM,
983 the buddy system, is also written to the disk. This can take
984 some time if the table is fragmented.
985 table(Name) -> QueryHandle
987 table(Name, Options) -> QueryHandle
989 Types:
991 Name = tab_name()
993 Options = Option | [Option]
994 Option = {n_objects, Limit} | {traverse, TraverseMethod}
995 Limit = default | integer() >= 1
996 TraverseMethod = first_next | select | {select, match_spec()}
997 QueryHandle = qlc:query_handle()
998 Returns a Query List Comprehension (QLC) query handle. The
1000 qlc(3) module provides a query language aimed mainly for Mnesia,
1001 but ETS tables, Dets tables, and lists are also recognized by
1002 qlc as sources of data. Calling dets:table/1,2 is the means to
1003 make Dets table Name usable to qlc.
1004 When there are only simple restrictions on the key position, qlc
1006 uses dets:lookup/2 to look up the keys. When that is not possi‐
1007 ble, the whole table is traversed. Option traverse determines
1008 how this is done:
1009 * first_next - The table is traversed one key at a time by
1011 calling dets:first/1 and dets:next/2.
1012 * select - The table is traversed by calling dets:select/3 and
1014 dets:select/1. Option n_objects determines the number of ob‐
1015 jects returned (the third argument of select/3). The match
1016 specification (the second argument of select/3) is assembled
1017 by qlc:
1018 * Simple filters are translated into equivalent match speci‐
1020 fications.
1021 * More complicated filters must be applied to all objects
1023 returned by select/3 given a match specification that
1024 matches all objects.
1025 * {select, match_spec()} - As for select, the table is tra‐
1027 versed by calling dets:select/3 and dets:select/1. The dif‐
1028 ference is that the match specification is specified explic‐
1029 itly. This is how to state match specifications that cannot
1030 easily be expressed within the syntax provided by qlc.
1031 The following example uses an explicit match specification to
1033 traverse the table:
1034 1> dets:open_file(t, []),
1036 ok = dets:insert(t, [{1,a},{2,b},{3,c},{4,d}]),
1037 MS = ets:fun2ms(fun({X,Y}) when (X > 1) or (X < 5) -> {Y} end),
1038 QH1 = dets:table(t, [{traverse, {select, MS}}]).
1039 An example with implicit match specification:
1041 2> QH2 = qlc:q([{Y} || {X,Y} <- dets:table(t), (X > 1) or (X < 5)]).
1043 The latter example is equivalent to the former, which can be
1045 verified using function qlc:info/1:
1046 3> qlc:info(QH1) =:= qlc:info(QH2).
1048 true
1049 qlc:info/1 returns information about a query handle. In this
1051 case identical information is returned for the two query han‐
1052 dles.
1053 to_ets(Name, EtsTab) -> EtsTab | {error, Reason}
1055 Types:
1057 Name = tab_name()
1059 EtsTab = ets:tab()
1060 Reason = term()
1061 Inserts the objects of the Dets table Name into the ETS table
1063 EtsTab. The order in which the objects are inserted is not spec‐
1064 ified. The existing objects of the ETS table are kept unless
1065 overwritten.
1066 traverse(Name, Fun) -> Return | {error, Reason}
1068 Types:
1070 Name = tab_name()
1072 Fun = fun((Object) -> FunReturn)
1073 Object = object()
1074 FunReturn =
1075 continue | {continue, Val} | {done, Value} | OtherValue
1076 Return = [term()] | OtherValue
1077 Val = Value = OtherValue = Reason = term()
1078 Applies Fun to each object stored in table Name in some unspeci‐
1080 fied order. Different actions are taken depending on the return
1081 value of Fun. The following Fun return values are allowed:
1082 continue:
1084 Continue to perform the traversal. For example, the follow‐
1085 ing function can be used to print the contents of a table:
1086 fun(X) -> io:format("~p~n", [X]), continue end.
1088 {continue, Val}:
1090 Continue the traversal and accumulate Val. The following
1091 function is supplied to collect all objects of a table in a
1092 list:
1093 fun(X) -> {continue, X} end.
1095 {done, Value}:
1097 Terminate the traversal and return [Value | Acc].
1098 Any other value OtherValue returned by Fun terminates the tra‐
1100 versal and is returned immediately.
1101 update_counter(Name, Key, Increment) -> Result
1103 Types:
1105 Name = tab_name()
1107 Key = term()
1108 Increment = {Pos, Incr} | Incr
1109 Pos = Incr = Result = integer()
1110 Updates the object with key Key stored in table Name of type set
1112 by adding Incr to the element at the Pos:th position. The new
1113 counter value is returned. If no position is specified, the ele‐
1114 ment directly following the key is updated.
1115 This functions provides a way of updating a counter, without
1117 having to look up an object, update the object by incrementing
1118 an element, and insert the resulting object into the table
1119 again.
1120
1122 ets(3), mnesia(3), qlc(3)
1123Ericsson AB stdlib 3.14.2.1 dets(3)