This module provides a term storage on file. The stored terms, in this module called objects, are tuples such that one element is defined to be the key. A Dets table is a collection of objects with the key at the same position stored on a file.
This module is used by the Mnesia application, and is provided "as is" for users who are interested in efficient storage of Erlang terms on disk only. Many applications only need to store some terms in a file. Mnesia adds transactions, queries, and distribution. The size of Dets files cannot exceed 2 GB. If larger tables are needed, table fragmentation in Mnesia can be used.
Three types of Dets tables exist:
Dets tables must be opened before they can be updated or read, and when finished they must be properly closed. If a table is not properly closed, Dets automatically repairs the table. This can take a substantial time if the table is large. A Dets table is closed when the process which opened the table terminates. If many Erlang processes (users) open the same Dets table, they share the table. The table is properly closed when all users have either terminated or closed the table. Dets tables are not properly closed if the Erlang runtime system terminates abnormally.
A
As all operations performed by Dets are disk operations, it
is important to realize that a single look-up operation involves a
series of disk seek and read operations. The Dets functions
are therefore much slower than the corresponding
Dets organizes data as a linear hash list and the hash list
grows gracefully as more data is inserted into the table. Space
management on the file is performed by what is called a buddy
system. The current implementation keeps the entire buddy system
in RAM, which implies that if the table gets heavily fragmented,
quite some memory can be used up. The only way to defragment a
table is to close it and then open it again with option
Notice that type
Two versions of the format used for storing objects on file are supported by Dets. The first version, 8, is the format always used for tables created by Erlang/OTP R7 and earlier. The second version, 9, is the default version of tables created by Erlang/OTP R8 (and later releases). Erlang/OTP R8 can create version 8 tables, and convert version 8 tables to version 9, and conversely, upon request.
All Dets functions return
Opaque continuation used by
Opaque continuation used by
Match specifications, see section
Opaque continuation used by
For a description of patterns, see
Opaque continuation used by
Returns a list of the names of all open tables on this node.
Returns a list of objects stored in a table. The exact
representation of the returned objects is not public. The
lists of data can be used for initializing a table by specifying
value
Unless the table is protected using
The first time
Closes a table. Only processes that have opened a table are allowed to close it.
All open tables must be closed before the system is stopped. If an attempt is made to open a table that is not properly closed, Dets automatically tries to repair it.
Deletes all objects with key
Deletes all objects from a table in almost constant time.
However, if the table if fixed,
Deletes all instances of a specified object from a table. If a
table is of type
Returns the first key stored in table
Unless the table is protected using
If an error occurs, the process is exited with an error
tuple
There are two reasons why
Calls
Deletes all objects of table
Returns information about table
Returns the information associated with
Replaces the existing objects of table
When called with argument
If the table type is
It is important that the table has a sufficient number of
slots for the objects. If not, the hash list starts to
grow when
Argument
Inserts one or more objects into the table
Inserts one or more objects into table
Returns
Returns
Returns a list of all objects with key
2> dets:open_file(abc, [{type, bag}]).
{ok,abc}
3> dets:insert(abc, {1,2,3}).
ok
4> dets:insert(abc, {1,3,4}).
ok
5> dets:lookup(abc, 1).
[{1,2,3},{1,3,4}]
If the table type is
Notice that the order of objects returned is unspecified. In particular, the order in which objects were inserted is not reflected.
Matches some objects stored in a table and returns a
non-empty list of the bindings matching a specified pattern in
some unspecified order. The table, the pattern, and the number
of objects that are matched are all defined by
When all table objects are matched,
Returns for each object of table
Matches some or all objects of table
A tuple of the bindings and a continuation is returned,
unless the table is empty, in which case
If the keypos'th element of
The table is always to be protected using
Deletes all objects that match
If the keypos'th element of
Returns a non-empty list of some objects stored in a table
that match a given pattern in some unspecified order. The
table, the pattern, and the number of objects that are matched
are all defined by
When all table objects are matched,
Returns a list of all objects of table
If the keypos'th element of
Using the
Matches some or all objects stored in table
A list of objects and a continuation is returned, unless
the table is empty, in which case
If the keypos'th element of
The table is always to be protected using
Works like
Returns either the key following
If an error occurs, the process is exited with an error
tuple
To find the first key in the table, use
Opens an existing table. If the table is not properly closed, it is repaired. The returned reference is to be used as the table name. This function is most useful for debugging purposes.
Opens a table. An empty Dets table is created if no file exists.
The atom
If two processes open the same table by giving the same name and arguments, the table has two users. If one user closes the table, it remains open until the second user closes it.
Argument
Value
Option
Returns the table name given the pid of a process
that handles requests to a table, or
This function is meant to be used for debugging only.
This function can be used to restore an opaque continuation
returned by
The reason for this function is that continuation terms
contain compiled match specifications and therefore are
invalidated if converted to external term format. Given that
the original match specification is kept intact, the
continuation can be restored, meaning it can once again be
used in subsequent
For more information and examples, see the
This function is rarely needed in application code. It is used by
application Mnesia to provide distributed
The reason for not having an external representation of compiled match specifications is performance. It can be subject to change in future releases, while this interface remains for backward compatibility.
If
If many processes fix a table, the table remains fixed until all processes have released it or terminated. A reference counter is kept on a per process basis, and N consecutive fixes require N releases to release the table.
It is not guaranteed that calls to
If objects have been added while the table was fixed, the hash list starts to grow when the table is released, which significantly slows down access to the table for a period of time.
Applies a match specification to some objects stored in a
table and returns a non-empty list of the results. The
table, the match specification, and the number of objects
that are matched are all defined by
When all objects of the table have been matched,
Returns the results of applying match specification
If the keypos'th element of
Using the
Returns the results of applying match specification
A tuple of the results of applying the match specification
and a continuation is returned, unless the table is empty,
in which case
If the keypos'th element of
The table is always to be protected using
Deletes each object from table
If the keypos'th element of
The objects of a table are distributed among slots,
starting with slot
Ensures that all updates made to table
Notice that the space management data structures kept in RAM, the buddy system, is also written to the disk. This can take some time if the table is fragmented.
Returns a Query List
Comprehension (QLC) query handle. The
When there are only simple restrictions on the key position,
Simple filters are translated into equivalent match specifications.
More complicated filters must be applied to all
objects returned by
The following example uses an explicit match specification to traverse the table:
1> dets:open_file(t, []),
ok = dets:insert(t, [{1,a},{2,b},{3,c},{4,d}]),
MS = ets:fun2ms(fun({X,Y}) when (X > 1) or (X < 5) -> {Y} end),
QH1 = dets:table(t, [{traverse, {select, MS}}]).
An example with implicit match specification:
2> QH2 = qlc:q([{Y} || {X,Y} <- dets:table(t), (X > 1) or (X < 5)]).
The latter example is equivalent to the former, which
can be verified using function
3> qlc:info(QH1) =:= qlc:info(QH2). true
Inserts the objects of the Dets table
Applies
Continue to perform the traversal. For example, the following function can be used to print the contents of a table:
fun(X) -> io:format("~p~n", [X]), continue end.
Continue the traversal and accumulate
fun(X) -> {continue, X} end.
Terminate the traversal and return
Any other value
Updates the object with key
This functions provides a way of updating a counter, without having to look up an object, update the object by incrementing an element, and insert the resulting object into the table again.