View Source DetsPlus (DetsPlus v1.0.1)

DetsPlus persistent tuple storage.

DetsPlus has a similiar API as dets but without the 2GB file storage limit. Writes are buffered in an internal ETS table and synced every auto_save period to the persistent storage.

While sync() or auto_save is in progress the database can still read and written.

There is no commitlog so not synced writes are lost. Lookups are possible by key and non-matches are accelerated using a bloom filter. The persistent file concept follows DJ Bernsteins CDB database format, but uses an Elixir encoded header https://cr.yp.to/cdb.html

Limits are:

  • Total file size: 18_446 Petabyte
  • Maximum entry size: 4 Gigabyte
  • Maximum entry count: :infinity

Link to this section Summary

Functions

Returns a specification to start this module under a supervisor.

Syncs pending writes to the persistent file and closes the table.

Returns information about table Name as a list of tuples

Returns the information associated with item for the table. The following items are allowed

Inserts one or more objects into the table. If there already exists an object with a key matching the key of some of the given objects, the old object will be replaced.

Inserts one or more objects into the table. If there already exists an object with a key matching the key of some of the given objects, the old object will be replaced.

Returns a list of all objects with key Key stored in the table.

Works like lookup/2, but does not return the objects. Returns true if one or more table elements has the key key, otherwise false.

Opens an existing table or creates a new table. If no file argument is provided the table name will be used.

Ensures that all updates made to table are written to disk. While the sync is running the table can still be used for reads and writes, but writes issed after the sync/1 call will not be part of the persistent file. These new changes will only be included in the next sync call.

Link to this section Functions

Returns a specification to start this module under a supervisor.

See Supervisor.

@spec close(atom() | pid()) :: :ok

Syncs pending writes to the persistent file and closes the table.

@spec info(atom() | pid()) :: [] | nil

Returns information about table Name as a list of tuples:

  • {file_size, integer() >= 0}} - The file size, in bytes.
  • {filename, file:name()} - The name of the file where objects are stored.
  • {keypos, keypos()} - The key position.
  • {size, integer() >= 0} - The number of objects estimated in the table.
  • {type, type()} - The table type.
@spec info(atom() | pid(), :file_size | :filename | :keypos | :size | :type) :: any()

Returns the information associated with item for the table. The following items are allowed:

  • {file_size, integer() >= 0}} - The file size, in bytes.
  • {filename, file:name()} - The name of the file where objects are stored.
  • {keypos, keypos()} - The key position.
  • {size, integer() >= 0} - The number of objects estimated in the table.
  • {type, type()} - The table type.
@spec insert(atom() | pid(), tuple()) :: :ok | {:error, atom()}

Inserts one or more objects into the table. If there already exists an object with a key matching the key of some of the given objects, the old object will be replaced.

Inserts one or more objects into the table. If there already exists an object with a key matching the key of some of the given objects, the old object will be replaced.

@spec lookup(atom() | pid(), any()) :: [tuple()] | {:error, atom()}

Returns a list of all objects with key Key stored in the table.

Example:

2> DetsPlus.open_file(:abc)
{ok,:abc}
3> DetsPlus.insert(:abc, {1,2,3})
ok
4> DetsPlus.insert(:abc, {1,3,4})
ok
5> DetsPlus.lookup(:abc, 1).
[{1,3,4}]

If the table type is set, the function returns either the empty list or a list with one object, as there cannot be more than one object with a given key. If the table type is bag or duplicate_bag, the function returns a list of arbitrary length.

Notice that the order of objects returned is unspecified. In particular, the order in which objects were inserted is not reflected.

@spec member(atom() | pid(), any()) :: false | true | {:error, atom()}

Same as member?/2

@spec member?(atom() | pid(), any()) :: false | true | {:error, atom()}

Works like lookup/2, but does not return the objects. Returns true if one or more table elements has the key key, otherwise false.

Link to this function

open_file(name, args \\ [])

View Source

Opens an existing table or creates a new table. If no file argument is provided the table name will be used.

Arguments:

  • auto_save - The autosave interval. If the interval is an integer Time, the table is flushed to disk whenever it is not accessed for Time milliseconds. A table that has been flushed requires no reparation when reopened after an uncontrolled emulator halt. If the interval is the atom infinity, autosave is disabled. Defaults to 180000 (3 minutes).
  • keypos - The position of the element of each object to be used as key. Defaults to 1. The ability to explicitly state the key position is most convenient when we want to store Erlang records in which the first position of the record is the name of the record type.
@spec sync(atom() | pid()) :: :ok

Ensures that all updates made to table are written to disk. While the sync is running the table can still be used for reads and writes, but writes issed after the sync/1 call will not be part of the persistent file. These new changes will only be included in the next sync call.