1dets(3)                    Erlang Module Definition                    dets(3)
2
3
4

NAME

6       dets - A disk-based term storage.
7

DESCRIPTION

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
14       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
21       Three types of Dets tables exist:
22
23         * 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
27         * bag. A table of this type has zero or more different objects with a
28           given key.
29
30         * duplicate_bag. A table of this  type  has  zero  or  more  possibly
31           matching objects with a given key.
32
33       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
43   Note:
44       A  ^C  command abnormally terminates an Erlang runtime system in a Unix
45       environment with a break-handler.
46
47
48       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
54       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
62       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
71       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

DATA TYPES

77       access() = read | read_write
78
79       auto_save() = infinity | integer() >= 0
80
81       bindings_cont()
82
83              Opaque continuation used by match/1 and match/3.
84
85       cont()
86
87              Opaque continuation used by bchunk/2.
88
89       keypos() = integer() >= 1
90
91       match_spec() = ets:match_spec()
92
93              Match specifications, see section  Match Specification in Erlang
94              in ERTS User's Guide and the ms_transform(3) module.
95
96       no_slots() = default | integer() >= 0
97
98       object() = tuple()
99
100       object_cont()
101
102              Opaque continuation used by match_object/1 and match_object/3.
103
104       pattern() = atom() | tuple()
105
106              For a description of patterns, see ets:match/2.
107
108       select_cont()
109
110              Opaque continuation used by select/1 and select/3.
111
112       tab_name() = term()
113
114       type() = bag | duplicate_bag | set
115

EXPORTS

117       all() -> [tab_name()]
118
119              Returns a list of the names of all open tables on this node.
120
121       bchunk(Name, Continuation) ->
122                 {Continuation2, Data} |
123                 '$end_of_table' |
124                 {error, Reason}
125
126              Types:
127
128                 Name = tab_name()
129                 Continuation = start | cont()
130                 Continuation2 = cont()
131                 Data = binary() | tuple()
132                 Reason = term()
133
134              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
140              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
144              The  first time bchunk/2 is called, an initial continuation, the
145              atom start, must be provided.
146
147              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
152              bchunk/2  returns '$end_of_table' when all objects are returned,
153              or {error, Reason} if an error occurs.
154
155       close(Name) -> ok | {error, Reason}
156
157              Types:
158
159                 Name = tab_name()
160                 Reason = term()
161
162              Closes a table. Only processes that  have  opened  a  table  are
163              allowed to close it.
164
165              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
169       delete(Name, Key) -> ok | {error, Reason}
170
171              Types:
172
173                 Name = tab_name()
174                 Key = Reason = term()
175
176              Deletes all objects with key Key from table Name.
177
178       delete_all_objects(Name) -> ok | {error, Reason}
179
180              Types:
181
182                 Name = tab_name()
183                 Reason = term()
184
185              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
189       delete_object(Name, Object) -> ok | {error, Reason}
190
191              Types:
192
193                 Name = tab_name()
194                 Object = object()
195                 Reason = term()
196
197              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
201       first(Name) -> Key | '$end_of_table'
202
203              Types:
204
205                 Name = tab_name()
206                 Key = term()
207
208              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
212              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
216              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
220              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
226       foldl(Function, Acc0, Name) -> Acc | {error, Reason}
227
228       foldr(Function, Acc0, Name) -> Acc | {error, Reason}
229
230              Types:
231
232                 Name = tab_name()
233                 Function = fun((Object :: object(), AccIn) -> AccOut)
234                 Acc0 = Acc = AccIn = AccOut = Reason = term()
235
236              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
242       from_ets(Name, EtsTab) -> ok | {error, Reason}
243
244              Types:
245
246                 Name = tab_name()
247                 EtsTab = ets:tab()
248                 Reason = term()
249
250              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
255       info(Name) -> InfoList | undefined
256
257              Types:
258
259                 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
268              Returns information about table Name as a list of tuples:
269
270                * {file_size, integer() >= 0}} - The file size, in bytes.
271
272                * {filename, file:name()} - The name of the file where objects
273                  are stored.
274
275                * {keypos, keypos()} - The key position.
276
277                * {size, integer() >= 0} - The number of objects stored in the
278                  table.
279
280                * {type, type()} - The table type.
281
282       info(Name, Item) -> Value | undefined
283
284              Types:
285
286                 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
296              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
300                * {access, access()} - The access mode.
301
302                * {auto_save, auto_save()} - The autosave interval.
303
304                * {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
308                * {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
312                  * phash - Implies that the erlang:phash/2 BIF is used.
313
314                  * phash2 - Implies that the erlang:phash2/1 BIF is used.
315
316                * {memory, integer() >= 0} - The file size, in bytes. The same
317                  value is associated with item file_size.
318
319                * {no_keys,  integer  >=  0()}  - The number of different keys
320                  stored in the table.
321
322                * {no_objects, integer >= 0()} - The number of objects  stored
323                  in the table.
324
325                * {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
330                * {owner, pid()}  -  The  pid  of  the  process  that  handles
331                  requests to the Dets table.
332
333                * {ram_file, boolean()} - Whether the table is kept in RAM.
334
335                * {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
342                  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
346                * {safe_fixed, SafeFixed}  -  The  same  as  {safe_fixed_mono‐
347                  tonic_time,  SafeFixed} except the format and value of Fixe‐
348                  dAtTime.
349
350                  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
357       init_table(Name, InitFun) -> ok | {error, Reason}
358
359       init_table(Name, InitFun, Options) -> ok | {error, Reason}
360
361              Types:
362
363                 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
376              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
383              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
391              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
398              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
405              Argument Options is a list of {Key, Val} tuples, where the  fol‐
406              lowing values are allowed:
407
408                * {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
414                * {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
421       insert(Name, Objects) -> ok | {error, Reason}
422
423              Types:
424
425                 Name = tab_name()
426                 Objects = object() | [object()]
427                 Reason = term()
428
429              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
434       insert_new(Name, Objects) -> boolean() | {error, Reason}
435
436              Types:
437
438                 Name = tab_name()
439                 Objects = object() | [object()]
440                 Reason = term()
441
442              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
447       is_compatible_bchunk_format(Name, BchunkFormat) -> boolean()
448
449              Types:
450
451                 Name = tab_name()
452                 BchunkFormat = binary()
453
454              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
459       is_dets_file(Filename) -> boolean() | {error, Reason}
460
461              Types:
462
463                 Filename = file:name()
464                 Reason = term()
465
466              Returns true if file Filename is a Dets table, otherwise false.
467
468       lookup(Name, Key) -> Objects | {error, Reason}
469
470              Types:
471
472                 Name = tab_name()
473                 Key = term()
474                 Objects = [object()]
475                 Reason = term()
476
477              Returns a list of all objects with key Key stored in table Name,
478              for example:
479
480              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
489              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
494              Notice  that  the  order  of objects returned is unspecified. In
495              particular, the order in which  objects  were  inserted  is  not
496              reflected.
497
498       match(Continuation) ->
499                {[Match], Continuation2} |
500                '$end_of_table' |
501                {error, Reason}
502
503              Types:
504
505                 Continuation = Continuation2 = bindings_cont()
506                 Match = [term()]
507                 Reason = term()
508
509              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
515              When all table objects are matched, '$end_of_table' is returned.
516
517       match(Name, Pattern) -> [Match] | {error, Reason}
518
519              Types:
520
521                 Name = tab_name()
522                 Pattern = pattern()
523                 Match = [term()]
524                 Reason = term()
525
526              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
533       match(Name, Pattern, N) ->
534                {[Match], Continuation} |
535                '$end_of_table' |
536                {error, Reason}
537
538              Types:
539
540                 Name = tab_name()
541                 Pattern = pattern()
542                 N = default | integer() >= 0
543                 Continuation = bindings_cont()
544                 Match = [term()]
545                 Reason = term()
546
547              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
551              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
556              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
565              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
569       match_delete(Name, Pattern) -> ok | {error, Reason}
570
571              Types:
572
573                 Name = tab_name()
574                 Pattern = pattern()
575                 Reason = term()
576
577              Deletes all objects that match Pattern from table  Name.  For  a
578              description of patterns, see ets:match/2.
579
580              If  the  keypos'th element of Pattern is bound, only the objects
581              with the correct key are matched.
582
583       match_object(Continuation) ->
584                       {Objects, Continuation2} |
585                       '$end_of_table' |
586                       {error, Reason}
587
588              Types:
589
590                 Continuation = Continuation2 = object_cont()
591                 Objects = [object()]
592                 Reason = term()
593
594              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
600              When all table objects are matched, '$end_of_table' is returned.
601
602       match_object(Name, Pattern) -> Objects | {error, Reason}
603
604              Types:
605
606                 Name = tab_name()
607                 Pattern = pattern()
608                 Objects = [object()]
609                 Reason = term()
610
611              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
615              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
619              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
623       match_object(Name, Pattern, N) ->
624                       {Objects, Continuation} |
625                       '$end_of_table' |
626                       {error, Reason}
627
628              Types:
629
630                 Name = tab_name()
631                 Pattern = pattern()
632                 N = default | integer() >= 0
633                 Continuation = object_cont()
634                 Objects = [object()]
635                 Reason = term()
636
637              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
641              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
646              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
656              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
660       member(Name, Key) -> boolean() | {error, Reason}
661
662              Types:
663
664                 Name = tab_name()
665                 Key = Reason = term()
666
667              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
670       next(Name, Key1) -> Key2 | '$end_of_table'
671
672              Types:
673
674                 Name = tab_name()
675                 Key1 = Key2 = term()
676
677              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
681              If an error occurs, the process is exited with  an  error  tuple
682              {error, Reason}.
683
684              To find the first key in the table, use first/1.
685
686       open_file(Filename) -> {ok, Reference} | {error, Reason}
687
688              Types:
689
690                 Filename = file:name()
691                 Reference = reference()
692                 Reason = term()
693
694              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
698       open_file(Name, Args) -> {ok, Name} | {error, Reason}
699
700              Types:
701
702                 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
717              Opens a table. An empty Dets table is created if no file exists.
718
719              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
724              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
728              Argument Args is a list of {Key, Val} tuples, where the  follow‐
729              ing values are allowed:
730
731                * {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
736                * {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
744                * {estimated_no_objects, no_slots()} -  Equivalent  to  option
745                  min_no_slots.
746
747                * {file,  file:name()}  -  The  name of the file to be opened.
748                  Defaults to the table name.
749
750                * {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
756                * {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
761                * {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
767                * {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
774                * {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
781                  Value  force means that a reparation is made even if the ta‐
782                  ble is properly closed. This is a seldom needed option.
783
784                  Option repair is ignored if the table is already open.
785
786                * {type, type()} - The table type. Defaults to set.
787
788       pid2name(Pid) -> {ok, Name} | undefined
789
790              Types:
791
792                 Pid = pid()
793                 Name = tab_name()
794
795              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
798              This function is meant to be used for debugging only.
799
800       repair_continuation(Continuation, MatchSpec) -> Continuation2
801
802              Types:
803
804                 Continuation = Continuation2 = select_cont()
805                 MatchSpec = match_spec()
806
807              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
812              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
819              For more information and examples, see the ets(3) module.
820
821          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
828              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
833
834       safe_fixtable(Name, Fix) -> ok
835
836              Types:
837
838                 Name = tab_name()
839                 Fix = boolean()
840
841              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
845              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
850              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
856              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
860       select(Continuation) ->
861                 {Selection, Continuation2} |
862                 '$end_of_table' |
863                 {error, Reason}
864
865              Types:
866
867                 Continuation = Continuation2 = select_cont()
868                 Selection = [term()]
869                 Reason = term()
870
871              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
877              When all objects of the table have been matched, '$end_of_table'
878              is returned.
879
880       select(Name, MatchSpec) -> Selection | {error, Reason}
881
882              Types:
883
884                 Name = tab_name()
885                 MatchSpec = match_spec()
886                 Selection = [term()]
887                 Reason = term()
888
889              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
894              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
899              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
902       select(Name, MatchSpec, N) ->
903                 {Selection, Continuation} |
904                 '$end_of_table' |
905                 {error, Reason}
906
907              Types:
908
909                 Name = tab_name()
910                 MatchSpec = match_spec()
911                 N = default | integer() >= 0
912                 Continuation = select_cont()
913                 Selection = [term()]
914                 Reason = term()
915
916              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
921              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
926              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
937              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
941       select_delete(Name, MatchSpec) -> N | {error, Reason}
942
943              Types:
944
945                 Name = tab_name()
946                 MatchSpec = match_spec()
947                 N = integer() >= 0
948                 Reason = term()
949
950              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
955              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
958       slot(Name, I) -> '$end_of_table' | Objects | {error, Reason}
959
960              Types:
961
962                 Name = tab_name()
963                 I = integer() >= 0
964                 Objects = [object()]
965                 Reason = term()
966
967              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
971       sync(Name) -> ok | {error, Reason}
972
973              Types:
974
975                 Name = tab_name()
976                 Reason = term()
977
978              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
983              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
987       table(Name) -> QueryHandle
988
989       table(Name, Options) -> QueryHandle
990
991              Types:
992
993                 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
1000              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
1006              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
1011                * first_next - The table is traversed one key  at  a  time  by
1012                  calling dets:first/1 and dets:next/2.
1013
1014                * 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
1020                  * Simple filters are translated into equivalent match speci‐
1021                    fications.
1022
1023                  * More complicated filters must be applied  to  all  objects
1024                    returned  by  select/3  given  a  match specification that
1025                    matches all objects.
1026
1027                * {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
1033              The following example uses an explicit  match  specification  to
1034              traverse the table:
1035
1036              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
1041              An example with implicit match specification:
1042
1043              2> QH2 = qlc:q([{Y} || {X,Y} <- dets:table(t), (X > 1) or (X < 5)]).
1044
1045              The  latter  example  is  equivalent to the former, which can be
1046              verified using function qlc:info/1:
1047
1048              3> qlc:info(QH1) =:= qlc:info(QH2).
1049              true
1050
1051              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
1055       to_ets(Name, EtsTab) -> EtsTab | {error, Reason}
1056
1057              Types:
1058
1059                 Name = tab_name()
1060                 EtsTab = ets:tab()
1061                 Reason = term()
1062
1063              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
1068       traverse(Name, Fun) -> Return | {error, Reason}
1069
1070              Types:
1071
1072                 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
1080              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
1084                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
1088                fun(X) -> io:format("~p~n", [X]), continue end.
1089
1090                {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
1095                fun(X) -> {continue, X} end.
1096
1097                {done, Value}:
1098                  Terminate the traversal and return [Value | Acc].
1099
1100              Any other value OtherValue returned by Fun terminates  the  tra‐
1101              versal and is returned immediately.
1102
1103       update_counter(Name, Key, Increment) -> Result
1104
1105              Types:
1106
1107                 Name = tab_name()
1108                 Key = term()
1109                 Increment = {Pos, Incr} | Incr
1110                 Pos = Incr = Result = integer()
1111
1112              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
1117              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

SEE ALSO

1123       ets(3), mnesia(3), qlc(3)
1124
1125
1126
1127Ericsson AB                       stdlib 3.10                          dets(3)
Impressum