The module
Dets is used by the Mnesia application, and is provided as is for users who are interested in an efficient storage of Erlang terms on disk only. Many applications just 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, Mnesia's table fragmentation can be used.
There are three types of Dets tables: set, bag and duplicate_bag. A table of type set has at most one object with a given key. If an object with a key already present in the table is inserted, the existing object is overwritten by the new object. A table of type bag has zero or more different objects with a given key. A table of type duplicate_bag has zero or more possibly matching objects with a given key.
Dets tables must be opened before they can be updated or read, and when finished they must be properly closed. If a table has not been properly closed, Dets will automatically repair 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 several Erlang processes (users) open the same Dets table, they will 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 is terminated abnormally.
A ^C command abnormally terminates an Erlang runtime system in a Unix environment with a break-handler.
Since 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. For this reason, the Dets functions are much slower than the corresponding Ets functions, although Dets exports a similar interface.
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 the
It is worth noting that the ordered_set type present in Ets is
not yet implemented by Dets, neither is the limited support for
concurrent updates which makes a sequence of
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 OTP R7 and earlier. The second version, 9, is the default version of tables created by OTP R8 (and later OTP releases). OTP R8 can create version 8 tables, and convert version 8 tables to version 9, and vice versa, upon request.
All Dets functions return
Types
access() = read | read_write auto_save() = infinity | int() bindings_cont() = tuple() bool() = true | false file() = string() int() = integer() >= 0 keypos() = integer() >= 1 name() = atom() | reference() no_slots() = integer() >= 0 | default object() = tuple() object_cont() = tuple() select_cont() = tuple() type() = bag | duplicate_bag | set version() = 8 | 9 | default
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 giving
the value
Unless the table is protected using
The first time
The
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 which has not been properly closed, Dets automatically tries to repair the table.
Deletes all objects with the key
Deletes all objects from a table in almost constant time.
However, if the table if fixed,
Deletes all instances of a given object from a table. If a
table is of type
Returns the first key stored in the table
Unless the table is protected using
Should an error occur, the process is exited with an error
tuple
There are two reasons why
Calls
Calls
Deletes all objects of the table
Returns information about the table
Returns the information associated with
Replaces the existing objects of the table
When called with the argument
If the type of the table is
It is important that the table has a sufficient number of
slots for the objects. If not, the hash list will start to
grow when
The
Inserts one or more objects into the table
Inserts one or more objects into the table
Returns
Returns
Returns a list of all objects with the 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 is of type
Note 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 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 objects of the table have been matched,
Returns for each object of the table
Matches some or all objects of the 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 should always 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 objects of the table have been matched,
Returns a list of all objects of the table
If the keypos'th element of
Using the
Matches some or all objects stored in the 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 should always be protected using
Works like
Returns the key following
Should an error occur, the process is exited with an error
tuple
Use
Opens an existing table. If the table has not been properly closed, it will be repaired. The returned reference is to be used as the name of the table. 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, then the table will have two users. If one user closes the table, it still remains open until the second user closes the table.
The
The value
The
Returns the name of the table 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 will be
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
See also
This function is very rarely needed in application code. It
is used by Mnesia to implement distributed
The reason for not having an external representation of compiled match specifications is performance. It may be subject to change in future releases, while this interface will remain for backward compatibility.
If
If several processes fix a table, the table will remain 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 will start to grow when the table is released which will significantly slow 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 the match specification
If the keypos'th element of
Using the
Returns the results of applying the 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 should always be protected using
Deletes each object from the 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 the table
Note that the space management data structures kept in RAM, the buddy system, is also written to the disk. This may take some time if the table is fragmented.
When there are only simple restrictions on the key position
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 in fact equivalent to the former which
can be verified using the 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 out 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 returned by
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.