From 68d53c01b0b8e9a007a6a30158c19e34b2d2a34e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Bj=C3=B6rn=20Gustavsson?= This module is an interface to the Erlang built-in term storage
BIFs. These provide the ability to store very large quantities of
data in an Erlang runtime system, and to have constant access
time to the data. (In the case of
Data is organized as a set of dynamic tables, which can store tuples. Each table is created by a process. When the process terminates, the table is automatically destroyed. Every table has access rights set at creation.
+Tables are divided into four different types,
The number of tables stored at one Erlang node is limited.
- The current default limit is approximately 1400 tables. The upper
- limit can be increased by setting the environment variable
+ The current default limit is about 1400 tables. The upper
+ limit can be increased by setting environment variable
Note that there is no automatic garbage collection for tables. + +
Notice that there is no automatic garbage collection for tables.
Even if there are no references to a table from any process, it
- will not automatically be destroyed unless the owner process
- terminates. It can be destroyed explicitly by using
-
Some implementation details:
+In the current implementation, every object insert and + look-up operation results in a copy of the object.
Also worth noting is the subtle difference between + +
Notice the subtle difference between
matching and comparing equal, which is
- demonstrated by the different table types
Two Erlang terms
Two Erlang terms compare equal
+ if they either are of the same type and value, or if
+ both are numeric types and extend to the same value, so that
+
The
In general, the functions below will exit with reason
-
The functions in this module exits with reason
+
This module provides some limited support for concurrent access. All updates to single objects are guaranteed to be both atomic - and isolated. This means that an updating operation towards - a single object will either succeed or fail completely without any - effect at all (atomicity). - Nor can any intermediate results of the update be seen by other - processes (isolation). Some functions that update several objects + and isolated. This means that an updating operation to + a single object either succeeds or fails completely without any + effect (atomicity) and that + no intermediate results of the update can be seen by other + processes (isolation). Some functions that update many objects state that they even guarantee atomicity and isolation for the entire operation. In database terms the isolation level can be seen as - "serializable", as if all isolated operations were carried out serially, + "serializable", as if all isolated operations are carried out serially, one after the other in a strict order.
-No other support is available within ETS that would guarantee
- consistency between objects. However, the
No other support is available within this module that would guarantee
+ consistency between objects. However, function
+
Some of the functions uses a match specification,
- match_spec. A brief explanation is given in
-
Some of the functions use a match specification,
+
Opaque continuation used by
A table identifier, as returned by new/2.
A table identifier, as returned by
+
Returns a list of all tables at the node. Named tables are - given by their names, unnamed tables are given by their + specified by their names, unnamed tables are specified by their table identifiers.
-There is no guarantee of consistency in the returned list. Tables created - or deleted by other processes "during" the ets:all() call may or may - not be included in the list. Only tables created/deleted before - ets:all() is called are guaranteed to be included/excluded.
+There is no guarantee of consistency in the returned list. Tables
+ created or deleted by other processes "during" the
Deletes the entire table
Deletes all objects with the key
Deletes all objects with key
Delete all objects in the ETS table
Delete the exact object
Delete the exact object
Reads a file produced by
Equivalent to
Reads a file produced by
Equivalent to
Reads a file produced by
Reads a file produced by
The currently only supported option is
If no
If verification is turned on and the file was written with
- the option
The only supported option is
If no
If verification is turned on and the file was written with
+ option
Returns the first key
Use
Returns the first key
To find subsequent keys in the table, use
+
If
If
If
If
Fills an already created ETS table with the objects in the
- already opened Dets table named
Throws a badarg error if any of the tables does not exist or the - dets table is not open.
+ already opened Dets tableIf any of the tables does not exist or the Dets table is
+ not open, a
Pseudo function that by means of a
Pseudo function that by a
The parse transform is implemented in the module
-
The parse transform is provided in the
The fun is very restricted, it can take only a single
parameter (the object to match): a sole variable or a
- tuple. It needs to use the
The return value is the resulting match_spec.
-Example:
+ tuple. It must use theThe return value is the resulting match specification.
+Example:
1> ets:fun2ms(fun({M,N}) when N > 3 -> M end). [{{'$1','$2'},[{'>','$2',3}],['$1']}]-
Variables from the environment can be imported, so that this - works:
+Variables from the environment can be imported, so that the + following works:
2> X=3. 3 3> ets:fun2ms(fun({M,N}) when N > X -> M end). [{{'$1','$2'},[{'>','$2',{const,3}}],['$1']}]-
The imported variables will be replaced by match_spec +
The imported variables are replaced by match specification
4> ets:fun2ms(fun({M,N}) when N > X, is_atomm(M) -> M end). Error: fun containing local Erlang function calls @@ -362,724 +405,832 @@ Error: fun containing local Erlang function calls {error,transform_error} 5> ets:fun2ms(fun({M,N}) when N > X, is_atom(M) -> M end). [{{'$1','$2'},[{'>','$2',{const,3}},{is_atom,'$1'}],['$1']}]-
As can be seen by the example, the function can be called - from the shell too. The fun needs to be literally in the call - when used from the shell as well. Other means than the - parse_transform are used in the shell case, but more or less - the same restrictions apply (the exception being records, - as they are not handled by the shell).
+As shown by the example, the function can be called + from the shell also. The fun must be literally in the call + when used from the shell as well.
If the parse_transform is not applied to a module which
- calls this pseudo function, the call will fail in runtime
- (with a
If the
For more information, see
-
For more information, see
Make process
The process
Note that
Make process
The process
Notice that this function does not affect option
+
Displays information about all ETS tables on tty.
+Displays information about all ETS tables on a terminal.
Browses the table
Browses table
Returns information about the table
Returns information about table
Indicates if the table is compressed.
+The pid of the heir of the table, or
The key position.
+The number of words allocated to the table.
+The table name.
+Indicates if the table is named.
+The node where the table is stored. This field is no longer + meaningful, as tables cannot be accessed from other nodes.
+The pid of the owner of the table.
+The table access rights.
+The number of objects inserted in the table.
+The table type.
+Indicates whether the table uses
Indicates whether the table uses
Returns the information associated with
In R11B and earlier, this function would not fail but return
-
In addition to the
Returns the information associated with
In Erlang/OTP R11B and earlier, this function would not fail but
+ return
In addition to the
-
Indicates if the table is fixed by any process.
+If the table has been fixed using
-
The format and value of
The format and value of
If the table never has been fixed, the call returns
-
- Returns internal statistics about set, bag and duplicate_bag tables on an internal format used by OTP test suites.
- Not for production use.
Returns internal statistics about
Replaces the existing objects of the table
Replaces the existing objects of table
When called with the argument
When called with argument
If the type of the table is
If the table type is
Inserts the object or all of the objects in the list
-
Inserts the object or all of the objects in list
+
If the table type is
If the table type is
If the list contains more than one object with
+ matching keys and the table type is
The entire operation is guaranteed to be
This function works exactly like
Same as
If
This function is used to check if a term is a valid
- compiled
Checks if a term is a valid
+ compiled
Examples:
+The following expression yields
ets:is_compiled_ms(ets:match_spec_compile([{'_',[],[true]}])).
- will yield
The following expressions yield
MS = ets:match_spec_compile([{'_',[],[true]}]),
Broken = binary_to_term(term_to_binary(MS)),
ets:is_compiled_ms(Broken).
- will yield false, as the variable
The fact that compiled match_specs has no external - representation is for performance reasons. It may be subject - to change in future releases, while this interface will - still remain for backward compatibility reasons.
+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.
Returns the last key
Use
Returns the last key
To find preceding keys in the table, use
+
Returns a list of all objects with the key
In the case of
Returns a list of all objects with key
For tables of type
For tables of type
The difference is the same as between
As an example, one can insert an object with
If the table is of type
For tables of type
Note that the time order of object insertions is preserved;
- the first object inserted with the given key will be first
+ key. For tables of type
Notice that the time order of object insertions is preserved; + the first object inserted with the specified key is the first in the resulting list, and so on.
-Insert and look-up times in tables of type
Insert and lookup times in tables of type
If the table
If the table is of type
If no object with the key
The difference between
For a table
For tables of type
If no object with key
The difference between
Continues a match started with
+
When there are no more objects in the table,
Matches the objects in the table
Matches the objects in table
A pattern is a term that may contain:
+A pattern is a term that can contain:
The function returns a list with one element for each matching object, where each element is an ordered list of - pattern variable bindings. An example:
+ pattern variable bindings, for example:-6> ets:match(T, '$1'). % Matches every object in the table +6> ets:match(T, '$1'). % Matches every object in table [[{rufsen,dog,7}],[{brunte,horse,5}],[{ludde,dog,5}]] 7> ets:match(T, {'_',dog,'$1'}). [[7],[5]] 8> ets:match(T, {'_',cow,'$1'}). []
If the key is specified in the pattern, the match is very - efficient. If the key is not specified, i.e. if it is a + efficient. If the key is not specified, that is, if it is a variable or an underscore, the entire table must be searched. The search time can be substantial if the table is very large.
-On tables of the
For tables of type
Works like
Works like
If the table is empty,
Continues a match started with
Deletes all objects that match pattern
Deletes all objects which match the pattern
Continues a match started with
+
When there are no more objects in the table,
Matches the objects in the table
Matches the objects in table
If the key is specified in the pattern, the match is very - efficient. If the key is not specified, i.e. if it is a + efficient. If the key is not specified, that is, if it is a variable or an underscore, the entire table must be searched. The search time can be substantial if the table is very large.
-On tables of the
For tables of type
Works like
Continues a match started with
Works like
If the table is empty,
This function transforms a
-
If the term
Transforms a
+
If term
This function has limited use in normal code, it is used by
- Dets to perform the
This function has limited use in normal code. It is used by the
+
This function executes the matching specified in a
- compiled
The matching will be executed on each element in
Executes the matching specified in a compiled
+
The matching is executed on each element in
Example:
+The following two calls give the same result (but certainly not the + same execution time):
Table = ets:new...
-MatchSpec = ....
+MatchSpec = ...
% The following call...
ets:match_spec_run(ets:tab2list(Table),
ets:match_spec_compile(MatchSpec)),
-% ...will give the same result as the more common (and more efficient)
-ets:select(Table,MatchSpec),
+% ...gives the same result as the more common (and more efficient)
+ets:select(Table, MatchSpec),
This function has limited use in normal code, it is used by
- Dets to perform the
This function has limited use in normal code. It is used by the
+
Works like
Works like
Creates a new table and returns a table identifier which can +
Creates a new table and returns a table identifier that can be used in subsequent operations. The table identifier can be sent to other processes so that a table can be shared between different processes within a node.
-The parameter
Parameter
The table is a
The table is a
The table is a
The table is a
Any process can read or write to the table.
+The owner process can read and write to the table. Other processes can only read the table. This is the default setting for the access rights.
+Only the owner process can read or write to the table.
If this option is present, name
Specifies which element in the stored tuples to use
+ as key. By default, it is the first element, that is,
+
Note that any tuple stored in the table must have at +
Notice that any tuple stored in the table must have at
least
- Set a process as heir. The heir will inherit the table if
- the owner terminates. The message
-
Set a process as heir. The heir inherits the table if
+ the owner terminates. Message
+
In current implementation, table type
Performance tuning. Defaults to
Option
Notice that this option does not change any guarantees about
+
Table type
Performance tuning. Defaults to
You typically want to enable this option when concurrent read + operations are much more frequent than write operations, or when + concurrent reads and writes comes in large read and write bursts + (that is, many reads not interrupted by writes, and many + writes not interrupted by reads).
+You typically do + not want to enable this option when the common access + pattern is a few read operations interleaved with a few write + operations repeatedly. In this case, you would get a performance + degradation by enabling this option.
+Option
If this option is present, the table data is stored in a more
+ compact format to consume less memory. However, it will make
+ table operations slower. Especially operations that need to
+ inspect entire objects, such as
Returns the next key
Use
Unless a table of type
Returns the next key
To find the first key in the table, use
+
Unless a table of type
Returns the previous key
Use
Returns the previous key
To find the last key in the table, use
+
Renames the named table
This function can be used to restore an opaque continuation
- returned by
Restores an opaque continuation returned by
+
The reason for this function is that continuation terms
- contain compiled match_specs and therefore will be
- invalidated if converted to external term format. Given that
- the original match_spec is kept intact, the continuation can
+ 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
-
As an example, the following sequence of calls will fail:
+Examples:
+The following sequence of calls fails:
T=ets:new(x,[]),
...
@@ -1089,7 +1240,9 @@ A
end),10),
Broken = binary_to_term(term_to_binary(C)),
ets:select(Broken).
- ...while the following sequence will work:
+The following sequence works, as the call to
+
T=ets:new(x,[]),
...
@@ -1100,45 +1253,44 @@ end),
{_,C} = ets:select(T,MS,10),
Broken = binary_to_term(term_to_binary(C)),
ets:select(ets:repair_continuation(Broken,MS)).
- ...as the call to
This function is very rarely needed in application code. It
- is used by Mnesia to implement distributed
This function is rarely needed in application code. It is used
+ by Mnesia to provide distributed
The reason for not having an external representation of a - compiled match_spec is performance. It may be subject to - change in future releases, while this interface will remain + compiled match specification is performance. It can be subject to + change in future releases, while this interface remains for backward compatibility.
Fixes a table of the
Fixes a table of type
A process fixes a table by calling
-
If several processes fix a table, the table will remain fixed +
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 requires N releases to actually release - the table.
-When a table is fixed, a sequence of
When a table is fixed, a sequence of
+
Example:
clean_all_with_value(Tab,X) ->
safe_fixtable(Tab,true),
@@ -1155,218 +1307,205 @@ clean_all_with_value(Tab,X,Key) ->
true
end,
clean_all_with_value(Tab,X,ets:next(Tab,Key)).
- Note that no deleted objects are actually removed from a +
Notice that no deleted objects are removed from a fixed table until it has been released. If a process fixes a table but never releases it, the memory used by the deleted - objects will never be freed. The performance of operations on - the table will also degrade significantly.
-Use
-
To retrieve information about which processes have fixed which
+ tables, use
Note that for tables of the
Notice that for table type
Continues a match started with
+
When there are no more objects in the table,
Matches the objects in the table
This means that the match_spec is always a list of one or
- more tuples (of arity 3). The tuples first element should be
- a pattern as described in the documentation of
-
Matches the objects in table
+MatchSpec = [MatchFunction]
+MatchFunction = {MatchHead, [Guard], [Result]}
+MatchHead = "Pattern as in ets:match"
+Guard = {"Guardtest name", ...}
+Result = "Term construct"
+ This means that the match specification is always a list of one or
+ more tuples (of arity 3). The first element of the tuple is to be
+ a pattern as described in
+
The return value is constructed using the "match variables"
- bound in the MatchHead or using the special match variables
+ bound in
ets:match(Tab,{'$1','$2','$3'})
is exactly equivalent to:
ets:select(Tab,[{{'$1','$2','$3'},[],['$$']}])
- - and the following
And that the following
ets:match_object(Tab,{'$1','$2','$1'})
is exactly equivalent to
ets:select(Tab,[{{'$1','$2','$1'},[],['$_']}])
Composite terms can be constructed in the
ets:select(Tab,[{{'$1','$2','$3'},[],['$$']}])
gives the same output as:
ets:select(Tab,[{{'$1','$2','$3'},[],[['$1','$2','$3']]}])
- i.e. all the bound variables in the match head as a list. If +
That is, all the bound variables in the match head as a list. If
tuples are to be constructed, one has to write a tuple of
- arity 1 with the single element in the tuple being the tuple
- one wants to construct (as an ordinary tuple could be mistaken
- for a
Therefore the following call:
ets:select(Tab,[{{'$1','$2','$1'},[],['$_']}])
gives the same output as:
ets:select(Tab,[{{'$1','$2','$1'},[],[{{'$1','$2','$3'}}]}])
- - this syntax is equivalent to the syntax used in the trace
- patterns (see
-
The
This syntax is equivalent to the syntax used in the trace
+ patterns (see the
+
The
The
- is expressed like this (X replaced with '$1' and Y with - '$2'):
+is expressed as follows (
- On tables of the
For tables of type
Works like
Continues a match started with
-
Works like
If the table is empty,
Matches the objects in the table
Matches the objects in table
The function could be described as a
This function can be described as a
+
The function returns the number of objects matched.
Matches the objects in the table
The function returns the number of objects actually +
Matches the objects in table
The function returns the number of objects deleted from the table.
The
The match specification has to return the atom
Works like
Works like
Note that this is not equivalent to
- reversing the result list of a
Continues a match started with
-
For all other table types, the behaviour is exactly that of
Example:
+Continues a match started with
Example:
1> T = ets:new(x,[ordered_set]).
2> [ ets:insert(T,{N}) || N <- lists:seq(1,10) ].
@@ -1384,217 +1523,288 @@ is_integer(X), is_integer(Y), X + Y < 4711]]>
8> R2.
[{2},{1}]
9> '$end_of_table' = ets:select_reverse(C2).
-...
-
+...
Works like
Works like
Notice that this is not equivalent to
+ reversing the result list of a
Set table options. The only option that currently is allowed to be
- set after the table has been created is
-
Sets table options. The only allowed option to be set after the
+ table has been created is
+
This function is mostly for debugging purposes, Normally
- one should use
Returns all objects in the
Returns all objects in slot
Unless a table of type
Unless a table of type
Dumps the table
Equivalent to
Dumps table
Equivalent to
+
Dumps the table
When dumping the table, certain information about the table - is dumped to a header at the beginning of the dump. This - information contains data about the table type, - name, protection, size, version and if it's a named table. It - also contains notes about what extended information is added - to the file, which can be a count of the objects in the file - or a MD5 sum of the header and records in the file.
-The size field in the header might not correspond to the - actual number of records in the file if the table is public - and records are added or removed from the table during - dumping. Public tables updated during dump, and that one wants - to verify when reading, needs at least one field of extended - information for the read verification process to be reliable - later.
-The
The number of objects actually written to the file is - noted in the file footer, why verification of file truncation - is possible even if the file was updated during - dump.
The header and objects in the file are checksummed using - the built in MD5 functions. The MD5 sum of all objects is - written in the file footer, so that verification while reading - will detect the slightest bitflip in the file data. Using this - costs a fair amount of CPU time.
Whenever the
The
Dumps table
When dumping the table, some information about the table + is dumped to a header at the beginning of the dump. This + information contains data about the table type, + name, protection, size, version, and if it is a named table. It + also contains notes about what extended information is added + to the file, which can be a count of the objects in the file + or a MD5 sum of the header and records in the file.
+The size field in the header might not correspond to the + number of records in the file if the table is public + and records are added or removed from the table during + dumping. Public tables updated during dump, and that one wants + to verify when reading, needs at least one field of extended + information for the read verification process to be reliable + later.
+Option
The number of objects written to the file is + noted in the file footer, so file truncation can be + verified even if the file was updated during dump.
+The header and objects in the file are checksummed using + the built-in MD5 functions. The MD5 sum of all objects is + written in the file footer, so that verification while reading + detects the slightest bitflip in the file data. Using this + costs a fair amount of CPU time.
+Whenever option
If option
Returns a list of all objects in the table
Returns a list of all objects in table
Returns information about the table dumped to file by
-
The following items are returned:
-The name of the dumped table. If the table was a
- named table, a table with the same name cannot exist when the
- table is loaded from file with
-
An error is returned if the file is inaccessible,
- badly damaged or not an file produced with
Returns information about the table dumped to file by
+
The following items are returned:
+The name of the dumped table. If the table was a
+ named table, a table with the same name cannot exist when the
+ table is loaded from file with
+
The ETS type of the dumped table (that is,
The protection of the dumped table (that is,
The
The number of objects in the table when the table dump
+ to file started. For a
The extended information written in the file footer to
+ allow stronger verification during table loading from file, as
+ specified to
A tuple
An error is returned if the file is inaccessible,
+ badly damaged, or not produced with
+
Returns a Query List
+ Comprehension (QLC) query handle. The
+
When there are only simple restrictions on the key position
- QLC uses
When there are only simple restrictions on the key position,
+ QLC uses
The table is traversed one key at a time by calling
+
The table is traversed one key at a time by calling
+
The table is traversed by calling
+
As for
The following example uses an explicit match_spec to - traverse the table:
+ +Examples:
+An explicit match specification is here used to traverse the + table:
9> true = ets:insert(Tab = ets:new(t, []), [{1,a},{2,b},{3,c},{4,d}]), MS = ets:fun2ms(fun({X,Y}) when (X > 1) or (X < 5) -> {Y} end), QH1 = ets:table(Tab, [{traverse, {select, MS}}]).-
An example with implicit match_spec:
+An example with an implicit match specification:
10> QH2 = qlc:q([{Y} || {X,Y} <- ets:table(Tab), (X > 1) or (X < 5)]).-
The latter example is in fact equivalent to the former which
- can be verified using the function
The latter example is equivalent to the former, which
+ can be verified using function
11> qlc:info(QH1) =:= qlc:info(QH2). true@@ -1603,52 +1813,60 @@ true two query handles.
Returns and removes a list of all objects with key
+
The specified
This function is a utility to test a
-
If the match specification is syntactically correct, the function
+ either returns
If the match specification contains errors, tuple
+
This is a useful debugging and test tool, especially when
- writing complicated
See also:
Returns a list of all objects with the key
The given
Fills an already created/opened Dets table with the objects
- in the already opened ETS table named
This function provides an efficient way to update one or more - counters, without the hassle of having to look up an object, update - the object by incrementing an element and insert the resulting object - into the table again. (The update is done atomically; i.e. no process - can access the ets table in the middle of the operation.) -
-It will destructively update the object with key
This function destructively update the object with key
+
If a
If a
A list of
The given
If a default object
A list of
The specified
If a default object
The function will fail with reason
The function fails with reason
This function provides an efficient way to update one or more - elements within an object, without the hassle of having to look up, - update and write back the entire object. -
-It will destructively update the object with key
A list of
The function returns
The given
The function will fail with reason
This function destructively updates the object with key
+
A list of
Returns
The specified
The function fails with reason