From 84adefa331c4159d432d22840663c38f155cd4c1 Mon Sep 17 00:00:00 2001 From: Erlang/OTP Date: Fri, 20 Nov 2009 14:54:40 +0000 Subject: The R13B03 release. --- lib/stdlib/doc/src/ets.xml | 1811 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 1811 insertions(+) create mode 100644 lib/stdlib/doc/src/ets.xml (limited to 'lib/stdlib/doc/src/ets.xml') diff --git a/lib/stdlib/doc/src/ets.xml b/lib/stdlib/doc/src/ets.xml new file mode 100644 index 0000000000..7b9f0e7772 --- /dev/null +++ b/lib/stdlib/doc/src/ets.xml @@ -0,0 +1,1811 @@ + + + + +
+ + 19962009 + Ericsson AB. All Rights Reserved. + + + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + + + ets + + + + +
+ ets + Built-In Term Storage + +

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 ordered_set, see below, + access time is proportional to the logarithm of the number of + objects stored).

+

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, set, + ordered_set, bag and duplicate_bag. + A set or ordered_set table can only have one object + associated with each key. A bag or duplicate_bag can + have many objects associated with each key.

+

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 + ERL_MAX_ETS_TABLES before starting the Erlang runtime + system (i.e. with the -env option to + erl/werl). The actual limit may be slightly higher + than the one specified, but never lower.

+

Note 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 + delete/1.

+

Since R13B01, table ownership can be transferred at process termination + by using the heir option or explicitly + by calling give_away/3.

+

Some implementation details:

+ + In the current implementation, every object insert and + look-up operation results in a copy of the object. + '$end_of_table' should not be used as a key since + this atom is used to mark the end of the table when using + first/next. + +

Also worth noting is the subtle difference between + matching and comparing equal, which is + demonstrated by the different table types set and + ordered_set. Two Erlang terms match if they are of + the same type and have the same value, so that 1 matches + 1, but not 1.0 (as 1.0 is a float() + and not an integer()). 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 + 1 compares equal to both 1 and 1.0. The + ordered_set works on the Erlang term order and + there is no defined order between an integer() and a + float() that extends to the same value, hence the key + 1 and the key 1.0 are regarded as equal in an + ordered_set table.

+

In general, the functions below will exit with reason + badarg if any argument is of the wrong format, or if the + table identifier is invalid.

+ + +
+ Concurrency +

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 (atomicy). + Nor can any intermediate results of the update be seen by other + processes (isolation). Some functions that update several objects + state that they even guarantee atomicy 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, + one after the other in a strict order.

+

No other support is available within ETS that would guarantee + consistency between objects. However, the safe_fixtable/2 + function can be used to guarantee that a sequence of + first/1 and next/2 calls will traverse the table + without errors and that each existing object in the table is visited + exactly once, even if another process (or the same process) + simultaneously deletes or inserts objects into the table. + Nothing more is guaranteed; in particular objects that are inserted + or deleted during such a traversal may be visited once or not at all. + Functions that internally traverse over a table, like select + and match, will give the same guarantee as safe_fixtable.

+
+
+ + Match Specifications +

Some of the functions uses a match specification, + match_spec. A brief explanation is given in + select/2. For a detailed + description, see the chapter "Match specifications in Erlang" in + ERTS User's Guide.

+
+ +
+ DATA TYPES + +match_spec() + a match specification, see above + +tid() + a table identifier, as returned by new/2 +
+ + + all() -> [Tab] + Return a list of all ETS tables. + + Tab = tid() | atom() + + +

Returns a list of all tables at the node. Named tables are + given by their names, unnamed tables are given by their + table identifiers.

+ + + + delete(Tab) -> true + Delete an entire ETS table. + + Tab = tid() | atom() + + +

Deletes the entire table Tab.

+ + + + delete(Tab, Key) -> true + Delete all objects with a given key from an ETS table. + + Tab = tid() | atom() + Key = term() + + +

Deletes all objects with the key Key from the table + Tab.

+ + + + delete_all_objects(Tab) -> true + Delete all objects in an ETS table. + + Tab = tid() | atom() + + +

Delete all objects in the ETS table Tab. + The operation is guaranteed to be + atomic and isolated.

+ + + + delete_object(Tab,Object) -> true + Deletes a specific from an ETS table. + + Tab = tid() | atom() + Object = tuple() + + +

Delete the exact object Object from the ETS table, + leaving objects with the same key but other differences + (useful for type bag). In a duplicate_bag, all + instances of the object will be deleted.

+ + + + file2tab(Filename) -> {ok,Tab} | {error,Reason} + Read an ETS table from a file. + + Filename = string() | atom() + Tab = tid() | atom() + Reason = term() + + +

Reads a file produced by tab2file/2 or + tab2file/3 and creates the + corresponding table Tab.

+

Equivalent to file2tab(Filename,[]).

+ + + + file2tab(Filename,Options) -> {ok,Tab} | {error,Reason} + Read an ETS table from a file. + + Filename = string() | atom() + Tab = tid() | atom() + Options = [Option] + Option = {verify, bool()} + Reason = term() + + +

Reads a file produced by tab2file/2 or + tab2file/3 and creates the + corresponding table Tab.

+

The currently only supported option is {verify,bool()}. If + verification is turned on (by means of specifying + {verify,true}), the function utilizes whatever + information is present in the file to assert that the + information is not damaged. How this is done depends on which + extended_info was written using + tab2file/3.

+

If no extended_info is present in the file and + {verify,true} is specified, the number of objects + written is compared to the size of the original table when the + dump was started. This might make verification fail if the + table was + public and objects were added or removed while the + table was dumped to file. To avoid this type of problems, + either do not verify files dumped while updated simultaneously + or use the {extended_info, [object_count]} option to + tab2file/3, which + extends the information in the file with the number of objects + actually written.

+

If verification is turned on and the file was written with + the option {extended_info, [md5sum]}, reading the file + is slower and consumes radically more CPU time than + otherwise.

+

{verify,false} is the default.

+ + + + first(Tab) -> Key | '$end_of_table' + Return the first key in an ETS table. + + Tab = tid() | atom() + Key = term() + + +

Returns the first key Key in the table Tab. + If the table is of the ordered_set type, the first key + in Erlang term order will be returned. If the table is of any + other type, the first key according to the table's internal + order will be returned. If the table is empty, + '$end_of_table' will be returned.

+

Use next/2 to find subsequent keys in the table.

+ + + + foldl(Function, Acc0, Tab) -> Acc1 + Fold a function over an ETS table + + Function = fun(A, AccIn) -> AccOut + Tab = tid() | atom() + Acc0 = Acc1 = AccIn = AccOut = term() + + +

Acc0 is returned if the table is empty. + This function is similar to lists:foldl/3. The order in + which the elements of the table are traversed is unspecified, + except for tables of type ordered_set, for which they + are traversed first to last.

+ +

If Function inserts objects into the table, or another + process inserts objects into the table, those objects may + (depending on key ordering) be included in the traversal.

+ + + + foldr(Function, Acc0, Tab) -> Acc1 + Fold a function over an ETS table + + Function = fun(A, AccIn) -> AccOut + Tab = tid() | atom() + Acc0 = Acc1 = AccIn = AccOut = term() + + +

Acc0 is returned if the table is empty. + This function is similar to lists:foldr/3. The order in + which the elements of the table are traversed is unspecified, + except for tables of type ordered_set, for which they + are traversed last to first.

+ +

If Function inserts objects into the table, or another + process inserts objects into the table, those objects may + (depending on key ordering) be included in the traversal.

+ + + + from_dets(Tab, DetsTab) -> true + Fill an ETS table with objects from a Dets table. + + Tab = tid() | atom() + DetsTab = atom() + + +

Fills an already created ETS table with the objects in the + already opened Dets table named DetsTab. The existing + objects of the ETS table are kept unless overwritten.

+

Throws a badarg error if any of the tables does not exist or the + dets table is not open.

+ + + + fun2ms(LiteralFun) -> MatchSpec + Pseudo function that transforms fun syntax to a match_spec. + + LiteralFun -- see below + MatchSpec = match_spec() + + +

Pseudo function that by means of a parse_transform + translates LiteralFun typed as parameter in the + function call to a + match_spec. With + "literal" is meant that the fun needs to textually be written + as the parameter of the function, it cannot be held in a + variable which in turn is passed to the function).

+

The parse transform is implemented in the module + ms_transform and the source must include the + file ms_transform.hrl in stdlib for this + pseudo function to work. Failing to include the hrl file in + the source will result in a runtime error, not a compile + time ditto. The include file is easiest included by adding + the line + -include_lib("stdlib/include/ms_transform.hrl"). to + the source file.

+

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 is_XXX guard tests. + Language constructs that have no representation + in a match_spec (like if, case, receive + etc) are not allowed.

+

The return value is the resulting match_spec.

+

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:

+ 
+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 + const expressions, which is consistent with the + static scoping for Erlang funs. Local or global function + calls can not be in the guard or body of the fun however. + Calls to builtin match_spec functions of course is allowed:

+ 
+4> ets:fun2ms(fun({M,N}) when N > X, is_atomm(M) -> M end).
+Error: fun containing local Erlang function calls
+('is_atomm' called in guard) cannot be translated into match_spec
+{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).

+ +

If the parse_transform is not applied to a module which + calls this pseudo function, the call will fail in runtime + (with a badarg). The module ets actually + exports a function with this name, but it should never + really be called except for when using the function in the + shell. If the parse_transform is properly applied by + including the ms_transform.hrl header file, compiled + code will never call the function, but the function call is + replaced by a literal match_spec.

+ +

For more information, see + ms_transform(3).

+ + + + give_away(Tab, Pid, GiftData) -> true + Change owner of a table. + + Tab = tid() | atom() + Pid = pid() + GiftData = term() + + +

Make process Pid the new owner of table Tab. + If successful, the message + {'ETS-TRANSFER',Tab,FromPid,GiftData} will be sent + to the new owner.

+

The process Pid must be alive, local and not already the + owner of the table. The calling process must be the table owner.

+

Note that give_away does not at all affect the + heir option of the table. A table + owner can for example set the heir to itself, give the table + away and then get it back in case the receiver terminates.

+ + + + i() -> ok + Display information about all ETS tables on tty. + +

Displays information about all ETS tables on tty.

+ + + + i(Tab) -> ok + Browse an ETS table on tty. + + Tab = tid() | atom() + + +

Browses the table Tab on tty.

+ + + + info(Tab) -> [{Item, Value}] | undefined + Return information about an ETS table. + + Tab = tid() | atom() + Item = atom(), see below + Value = term(), see below + + +

Returns information about the table Tab as a list of + {Item, Value} tuples. If Tab has the correct type + for a table identifier, but does not refer to an existing ETS + table, undefined is returned. If Tab is not of the + correct type, this function fails with reason badarg.

+ + + Item=memory, Value=int()

+ + The number of words allocated to the table. + Item=owner, Value=pid()

+ + The pid of the owner of the table. + Item=heir, Value=pid()|none

+ + The pid of the heir of the table, or none if no heir is set. + Item=name, Value=atom()

+ + The name of the table. + Item=size, Value=int()

+ + The number of objects inserted in the table. + Item=node, Value=atom()

+ + The node where the table is stored. This field is no longer + meaningful as tables cannot be accessed from other nodes. + Item=named_table, Value=true|false

+ + Indicates if the table is named or not. + Item=type, Value=set|ordered_set|bag|duplicate_bag

+ + The table type. + Item=keypos, Value=int()

+ + The key position. + Item=protection, Value=public|protected|private

+ + The table access rights. + + + + + info(Tab, Item) -> Value | undefined + Return the information associated with given item for an ETS table. + + Tab = tid() | atom() + Item, Value - see below + + +

Returns the information associated with Item for + the table Tab, or returns undefined if Tab + does not refer an existing ETS table. + If Tab is not of the correct type, or if Item is not + one of the allowed values, this function fails with reason badarg.

+ +

In R11B and earlier, this function would not fail but return + undefined for invalid values for Item.

+ + +

In addition to the {Item,Value} + pairs defined for info/1, the following items are + allowed:

+ + Item=fixed, Value=true|false

+ + Indicates if the table is fixed by any process or not. + +

Item=safe_fixed, Value={FirstFixed,Info}|false

+

+

If the table has been fixed using safe_fixtable/2, + the call returns a tuple where FirstFixed is the + time when the table was first fixed by a process, which + may or may not be one of the processes it is fixed by + right now.

+

Info is a possibly empty lists of tuples + {Pid,RefCount}, one tuple for every process the + table is fixed by right now. RefCount is the value + of the reference counter, keeping track of how many times + the table has been fixed by the process.

+

If the table never has been fixed, the call returns + false.

+ + + + + + init_table(Name, InitFun) -> true + Replace all objects of an ETS table. + + Name = atom() + InitFun = fun(Arg) -> Res + Arg = read | close + Res = end_of_input | {[object()], InitFun} | term() + + +

Replaces the existing objects of the table Tab with + objects created by calling the input function InitFun, + see below. This function is provided for compatibility with + the dets module, it is not more efficient than filling + a table by using ets:insert/2. +

+

When called with the argument read the function + InitFun is assumed to return end_of_input when + there is no more input, or {Objects, Fun}, where + Objects is a list of objects and Fun is a new + input function. Any other value Value is returned as an error + {error, {init_fun, Value}}. Each input function will be + called exactly once, and should an error occur, the last + function is called with the argument close, the reply + of which is ignored.

+

If the type of the table is set and there is more + than one object with a given key, one of the objects is + chosen. This is not necessarily the last object with the given + key in the sequence of objects returned by the input + functions. This holds also for duplicated + objects stored in tables of type bag.

+ + + + insert(Tab, ObjectOrObjects) -> true + Insert an object into an ETS table. + + Tab = tid() | atom() + ObjectOrObjects = tuple() | [tuple()] + + +

Inserts the object or all of the objects in the list + ObjectOrObjects into the table Tab. + If the table is a set and the key of the inserted + objects matches the key of any object in the table, + the old object will be replaced. If the table is an + ordered_set and the key of the inserted object + compares equal to the key of any object in the + table, the old object is also replaced. If the list contains + more than one object with matching keys and the table is a + set, one will be inserted, which one is + not defined. The same thing holds for ordered_set, but + will also happen if the keys compare equal.

+

The entire operation is guaranteed to be + atomic and isolated, + even when a list of objects is inserted.

+ + + + insert_new(Tab, ObjectOrObjects) -> bool() + Insert an object into an ETS table if the key is not already present. + + Tab = tid() | atom() + ObjectOrObjects = tuple() | [tuple()] + + +

This function works exactly like insert/2, with the + exception that instead of overwriting objects with the same + key (in the case of set or ordered_set) or + adding more objects with keys already existing in the table + (in the case of bag and duplicate_bag), it + simply returns false. If ObjectOrObjects is a + list, the function checks every key prior to + inserting anything. Nothing will be inserted if not + all keys present in the list are absent from the + table. Like insert/2, the entire operation is guaranteed to be + atomic and isolated.

+ + + + is_compiled_ms(Term) -> bool() + Checks if an Erlang term is the result of ets:match_spec_compile + + Term = term() + + +

This function is used to check if a term is a valid + compiled match_spec. + The compiled match_spec is an opaque datatype which can + not be sent between Erlang nodes nor be stored on + disk. Any attempt to create an external representation of a + compiled match_spec will result in an empty binary + (>]]>). As an example, the following + expression:

+ +ets:is_compiled_ms(ets:match_spec_compile([{'_',[],[true]}])). +

will yield true, while the following expressions:

+ +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 Broken will contain + a compiled match_spec that has passed through external + representation.

+ +

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.

+ + + + + last(Tab) -> Key | '$end_of_table' + Return the last key in an ETS table of typeordered_set. + + Tab = tid() | atom() + Key = term() + + +

Returns the last key Key according to Erlang term + order in the table Tab of the ordered_set type. + If the table is of any other type, the function is synonymous + to first/2. If the table is empty, + '$end_of_table' is returned.

+

Use prev/2 to find preceding keys in the table.

+ + + + lookup(Tab, Key) -> [Object] + Return all objects with a given key in an ETS table. + + Tab = tid() | atom() + Key = term() + Object = tuple() + + +

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

+

In the case of set, bag and duplicate_bag, an object + is returned only if the given key matches the key + of the object in the table. If the table is an + ordered_set however, an object is returned if the key + given compares equal to the key of an object in the + table. The difference being the same as between =:= + and ==. As an example, one might insert an object + with the + integer()1 as a key in an ordered_set + and get the object returned as a result of doing a + lookup/2 with the float()1.0 as the + key to search for.

+

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

+

Note that the time order of object insertions is preserved; + The first object inserted with the given key will be first + in the resulting list, and so on.

+

Insert and look-up times in tables of type set, + bag and duplicate_bag are constant, regardless + of the size of the table. For the ordered_set + data-type, time is proportional to the (binary) logarithm of + the number of objects.

+ + + + lookup_element(Tab, Key, Pos) -> Elem + Return the Pos:th element of all objects with a given key in an ETS table. + + Tab = tid() | atom() + Key = term() + Pos = int() + Elem = term() | [term()] + + +

If the table Tab is of type set or + ordered_set, the function returns the Pos:th + element of the object with the key Key.

+

If the table is of type bag or duplicate_bag, + the functions returns a list with the Pos:th element of + every object with the key Key.

+

If no object with the key Key exists, the function + will exit with reason badarg.

+

The difference between set, bag and + duplicate_bag on one hand, and ordered_set on + the other, regarding the fact that ordered_set's + view keys as equal when they compare equal + whereas the other table types only regard them equal when + they match, naturally holds for + lookup_element as well as for lookup.

+ + + + match(Tab, Pattern) -> [Match] + Match the objects in an ETS table against a pattern. + + Tab = tid() | atom() + Pattern = tuple() + Match = [term()] + + +

Matches the objects in the table Tab against the + pattern Pattern.

+

A pattern is a term that may contain:

+ + bound parts (Erlang terms), + '_' which matches any Erlang term, and + pattern variables: '$N' where + N=0,1,... + +

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:

+ 
+6> ets:match(T, '$1'). % Matches every object in the 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 + 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 ordered_set type, the result is in + the same order as in a first/next traversal.

+ + + + match(Tab, Pattern, Limit) -> {[Match],Continuation} | '$end_of_table' + Match the objects in an ETS table against a pattern and returns part of the answers. + + Tab = tid() | atom() + Pattern = tuple() + Match = [term()] + Continuation = term() + + +

Works like ets:match/2 but only returns a limited + (Limit) number of matching objects. The + Continuation term can then be used in subsequent calls + to ets:match/1 to get the next chunk of matching + objects. This is a space efficient way to work on objects in a + table which is still faster than traversing the table object + by object using ets:first/1 and ets:next/1.

+

'$end_of_table' is returned if the table is empty.

+ + + + match(Continuation) -> {[Match],Continuation} | '$end_of_table' + Continues matching objects in an ETS table. + + Match = [term()] + Continuation = term() + + +

Continues a match started with ets:match/3. The next + chunk of the size given in the initial ets:match/3 + call is returned together with a new Continuation + that can be used in subsequent calls to this function.

+

'$end_of_table' is returned when there are no more + objects in the table.

+ + + + match_delete(Tab, Pattern) -> true + Delete all objects which match a given pattern from an ETS table. + + Tab = tid() | atom() + Pattern = tuple() + + +

Deletes all objects which match the pattern Pattern + from the table Tab. See match/2 for a + description of patterns.

+ + + + match_object(Tab, Pattern) -> [Object] + Match the objects in an ETS table against a pattern. + + Tab = tid() | atom() + Pattern = Object = tuple() + + +

Matches the objects in the table Tab against the + pattern Pattern. See match/2 for a description + of patterns. The function returns a list of all objects which + match the pattern.

+

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 + 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 ordered_set type, the result is in + the same order as in a first/next traversal.

+ + + + match_object(Tab, Pattern, Limit) -> {[Match],Continuation} | '$end_of_table' + Match the objects in an ETS table against a pattern and returns part of the answers. + + Tab = tid() | atom() + Pattern = tuple() + Match = [term()] + Continuation = term() + + +

Works like ets:match_object/2 but only returns a + limited (Limit) number of matching objects. The + Continuation term can then be used in subsequent calls + to ets:match_object/1 to get the next chunk of matching + objects. This is a space efficient way to work on objects in a + table which is still faster than traversing the table object + by object using ets:first/1 and ets:next/1.

+

'$end_of_table' is returned if the table is empty.

+ + + + match_object(Continuation) -> {[Match],Continuation} | '$end_of_table' + Continues matching objects in an ETS table. + + Match = [term()] + Continuation = term() + + +

Continues a match started with ets:match_object/3. + The next chunk of the size given in the initial + ets:match_object/3 call is returned together with a + new Continuation that can be used in subsequent calls + to this function.

+

'$end_of_table' is returned when there are no more + objects in the table.

+ + + + match_spec_compile(MatchSpec) -> CompiledMatchSpec + Compiles a match specification into its internal representation + + MatchSpec = match_spec() + CompiledMatchSpec = comp_match_spec() + + +

This function transforms a + match_spec into an + internal representation that can be used in subsequent calls + to ets:match_spec_run/2. The internal representation is + opaque and can not be converted to external term format and + then back again without losing its properties (meaning it can + not be sent to a process on another node and still remain a + valid compiled match_spec, nor can it be stored on disk). + The validity of a compiled match_spec can be checked using + ets:is_compiled_ms/1.

+

If the term MatchSpec can not be compiled (does not + represent a valid match_spec), a badarg fault is + thrown.

+ +

This function has limited use in normal code, it is used by + Dets to perform the dets:select operations.

+ + + + + match_spec_run(List,CompiledMatchSpec) -> list() + Performs matching, using a compiled match_spec, on a list of tuples + + List = [ tuple() ] + CompiledMatchSpec = comp_match_spec() + + +

This function executes the matching specified in a + compiled match_spec on + a list of tuples. The CompiledMatchSpec term should be + the result of a call to ets:match_spec_compile/1 and + is hence the internal representation of the match_spec one + wants to use.

+

The matching will be executed on each element in List + and the function returns a list containing all results. If an + element in List does not match, nothing is returned + for that element. The length of the result list is therefore + equal or less than the the length of the parameter + List. The two calls in the following example will give + the same result (but certainly not the same execution + time...):

+ +Table = ets:new... +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), + +

This function has limited use in normal code, it is used by + Dets to perform the dets:select operations and by + Mnesia during transactions.

+ + + + + member(Tab, Key) -> true | false + Tests for occurrence of a key in an ETS table + + Tab = tid() | atom() + Key = term() + + +

Works like lookup/2, but does not return the objects. + The function returns true if one or more elements in + the table has the key Key, false otherwise.

+ + + + new(Name, Options) -> tid() | atom() + Create a new ETS table. + + Name = atom() + Options = [Option] +  Option = Type | Access | named_table | {keypos,Pos} | {heir,pid(),HeirData} | {heir,none} | {write_concurrency,bool()} +   Type = set | ordered_set | bag | duplicate_bag +   Access = public | protected | private +   Pos = int() +   HeirData = term() + + +

Creates a new table and returns a table identifier which 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 Options is a list of atoms which + specifies table type, access rights, key position and if the + table is named or not. If one or more options are left out, + the default values are used. This means that not specifying + any options ([]) is the same as specifying + [set,protected,{keypos,1},{heir,none},{write_concurrency,false}].

+ + +

set + The table is a set table - one key, one object, + no order among objects. This is the default table type.

+ + +

ordered_set + The table is a ordered_set table - one key, one + object, ordered in Erlang term order, which is the order + implied by the < and > operators. Tables of this type + have a somewhat different behavior in some situations + than tables of the other types. Most notably the + ordered_set tables regard keys as equal when they + compare equal, not only when they match. This + means that to an ordered_set, the + integer()1 and the float()1.0 are regarded as equal. This also means that the + key used to lookup an element not necessarily + matches the key in the elements returned, if + float()'s and integer()'s are mixed in + keys of a table.

+ + +

bag + The table is a bag table which can have many + objects, but only one instance of each object, per key.

+ + +

duplicate_bag + The table is a duplicate_bag table which can have + many objects, including multiple copies of the same + object, per key.

+ + +

public + Any process may read or write to the table.

+ + +

protected + 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.

+ + +

private + Only the owner process can read or write to the table.

+ + +

named_table + If this option is present, the name Name is + associated with the table identifier. The name can then + be used instead of the table identifier in subsequent + operations.

+ + +

{keypos,Pos} + Specfies which element in the stored tuples should be + used as key. By default, it is the first element, i.e. + Pos=1. However, this is not always appropriate. In + particular, we do not want the first element to be the + key if we want to store Erlang records in a table.

+

Note that any tuple stored in the table must have at + least Pos number of elements.

+ + + +

{heir,Pid,HeirData} | {heir,none}

+ Set a process as heir. The heir will inherit the table if + the owner terminates. The message + {'ETS-TRANSFER',tid(),FromPid,HeirData} will be sent to + the heir when that happens. The heir must be a local process. + Default heir is none, which will destroy the table when + the owner terminates.

+ + +

{write_concurrency,bool()} + Performance tuning. Default is false, which means that the table + is optimized towards concurrent read access. An operation that + mutates (writes to) the table will obtain exclusive access, + blocking any concurrent access of the same table until finished. + If set to true, the table is optimized towards concurrent + write access. Different objects of the same table can be mutated + (and read) by concurrent processes. This is achieved to some degree + at the expense of single access and concurrent reader performance. + Note that this option does not change any guarantees about + atomicy and isolation. + Functions that makes such promises over several objects (like + insert/2) will gain less (or nothing) from this option.

+

Table type ordered_set is not affected by this option in current + implementation.

+ + + + + + next(Tab, Key1) -> Key2 | '$end_of_table' + Return the next key in an ETS table. + + Tab = tid() | atom() + Key1 = Key2 = term() + + +

Returns the next key Key2, following the key + Key1 in the table Tab. If the table is of the + ordered_set type, the next key in Erlang term order is + returned. If the table is of any other type, the next key + according to the table's internal order is returned. If there + is no next key, '$end_of_table' is returned.

+

Use first/1 to find the first key in the table.

+

Unless a table of type set, bag or + duplicate_bag is protected using + safe_fixtable/2, see below, a traversal may fail if + concurrent updates are made to the table. If the table is of + type ordered_set, the function returns the next key in + order, even if the object does no longer exist.

+ + + + prev(Tab, Key1) -> Key2 | '$end_of_table' + Return the previous key in an ETS table of typeordered_set. + + Tab = tid() | atom() + Key1 = Key2 = term() + + +

Returns the previous key Key2, preceding the key + Key1 according the Erlang term order in the table + Tab of the ordered_set type. If the table is of + any other type, the function is synonymous to next/2. + If there is no previous key, '$end_of_table' is + returned.

+

Use last/1 to find the last key in the table.

+ + + + rename(Tab, Name) -> Name + Rename a named ETS table. + + Tab = Name = atom() + + +

Renames the named table Tab to the new name + Name. Afterwards, the old name can not be used to + access the table. Renaming an unnamed table has no effect.

+ + + + repair_continuation(Continuation, MatchSpec) -> Continuation + Repair a continuation from ets:select/1 or ets:select/3 that has passed through external representation + + Continuation = term() + MatchSpec = match_spec() + + +

This function can be used to restore an opaque continuation + returned by ets:select/3 or ets:select/1 if the + continuation has passed through external term format (been + sent between nodes or stored on disk).

+

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 + be restored, meaning it can once again be used in subsequent + ets:select/1 calls even though it has been stored on + disk or on another node.

+

As an example, the following sequence of calls will fail:

+ +T=ets:new(x,[]), +... +{_,C} = ets:select(T,ets:fun2ms(fun({N,_}=A) +when (N rem 10) =:= 0 -> +A +end),10), +Broken = binary_to_term(term_to_binary(C)), +ets:select(Broken). +

...while the following sequence will work:

+ +T=ets:new(x,[]), +... +MS = ets:fun2ms(fun({N,_}=A) +when (N rem 10) =:= 0 -> +A +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 ets:repair_continuation/2 will + reestablish the (deliberately) invalidated continuation + Broken.

+ +

This function is very rarely needed in application code. It + is used by Mnesia to implement distributed select/3 + and select/1 sequences. A normal application would + either use Mnesia or keep the continuation from being + converted to external format.

+

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 + for backward compatibility.

+ + + + + safe_fixtable(Tab, true|false) -> true + Fix an ETS table for safe traversal. + + Tab = tid() | atom() + + +

Fixes a table of the set, bag or + duplicate_bag table type for safe traversal.

+

A process fixes a table by calling + safe_fixtable(Tab,true). The table remains fixed until + the process releases it by calling + safe_fixtable(Tab,false), or until the process + terminates.

+

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 requires N releases to actually release + the table.

+

When a table is fixed, a sequence of first/1 and + next/2 calls are guaranteed to succeed and each object in + the table will only be returned once, even if objects + are removed or inserted during the traversal. + The keys for new objects inserted during the traversal may + be returned by next/2 + (it depends on the internal ordering of the keys). An example:

+ +clean_all_with_value(Tab,X) -> + safe_fixtable(Tab,true), + clean_all_with_value(Tab,X,ets:first(Tab)), + safe_fixtable(Tab,false). + +clean_all_with_value(Tab,X,'$end_of_table') -> + true; +clean_all_with_value(Tab,X,Key) -> + case ets:lookup(Tab,Key) of + [{Key,X}] -> + ets:delete(Tab,Key); + _ -> + true + end, + clean_all_with_value(Tab,X,ets:next(Tab,Key)). +

Note that no deleted objects are actually 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 info/2 to retrieve information about which + processes have fixed which tables. A system with a lot of + processes fixing tables may need a monitor which sends alarms + when tables have been fixed for too long.

+

Note that for tables of the ordered_set type, + safe_fixtable/2 is not necessary as calls to + first/1 and next/2 will always succeed.

+ + + + select(Tab, MatchSpec) -> [Match] + Match the objects in an ETS table against a match_spec. + + Tab = tid() | atom() + Match = term() + MatchSpec = match_spec() + + +

Matches the objects in the table Tab using a + match_spec. This is a + more general call than the ets:match/2 and + ets:match_object/2 calls. In its simplest forms the + match_specs look like this:

+ + MatchSpec = [MatchFunction] + MatchFunction = {MatchHead, [Guard], [Result]} + MatchHead = "Pattern as in ets:match" + Guard = {"Guardtest name", ...} + Result = "Term construct" + +

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 + ets:match/2. The second element of the tuple should + be a list of 0 or more guard tests (described below). The + third element of the tuple should be a list containing a + description of the value to actually return. In almost all + normal cases the list contains exactly one term which fully + describes the value to return for each object.

+

The return value is constructed using the "match variables" + bound in the MatchHead or using the special match variables + '$_' (the whole matching object) and '$$' (all + match variables in a list), so that the following + ets:match/2 expression:

+ +ets:match(Tab,{'$1','$2','$3'}) +

is exactly equivalent to:

+ +ets:select(Tab,[{{'$1','$2','$3'},[],['$$']}]) +

- and the following ets:match_object/2 call:

+ +ets:match_object(Tab,{'$1','$2','$1'}) +

is exactly equivalent to

+ +ets:select(Tab,[{{'$1','$2','$1'},[],['$_']}]) +

Composite terms can be constructed in the Result part + either by simply writing a list, so that this code:

+ +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 + 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 Guard). 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 + dbg(3)).

+

The Guards are constructed as tuples where the first + element is the name of the test and the rest of the elements + are the parameters of the test. To check for a specific type + (say a list) of the element bound to the match variable + '$1', one would write the test as + {is_list, '$1'}. If the test fails, the object in the + table will not match and the next MatchFunction (if + any) will be tried. Most guard tests present in Erlang can be + used, but only the new versions prefixed is_ are + allowed (like is_float, is_atom etc).

+

The Guard section can also contain logic and + arithmetic operations, which are written with the same syntax + as the guard tests (prefix notation), so that a guard test + written in Erlang looking like this:

+ +

is expressed like this (X replaced with '$1' and Y with + '$2'):

+ +

On tables of the ordered_set type, objects are visited + in the same order as in a first/next + traversal. This means that the match specification will be + executed against objects with keys in the first/next + order and the corresponding result list will be in the order of that + execution.

+ + + + + select(Tab, MatchSpec, Limit) -> {[Match],Continuation} | '$end_of_table' + Match the objects in an ETS table against a match_spec and returns part of the answers. + + Tab = tid() | atom() + Match = term() + MatchSpec = match_spec() + Continuation = term() + + +

Works like ets:select/2 but only returns a limited + (Limit) number of matching objects. The + Continuation term can then be used in subsequent calls + to ets:select/1 to get the next chunk of matching + objects. This is a space efficient way to work on objects in a + table which is still faster than traversing the table object + by object using ets:first/1 and ets:next/1.

+

'$end_of_table' is returned if the table is empty.

+ + + + select(Continuation) -> {[Match],Continuation} | '$end_of_table' + Continue matching objects in an ETS table. + + Match = term() + Continuation = term() + + +

Continues a match started with + ets:select/3. The next + chunk of the size given in the initial ets:select/3 + call is returned together with a new Continuation + that can be used in subsequent calls to this function.

+

'$end_of_table' is returned when there are no more + objects in the table.

+ + + + select_delete(Tab, MatchSpec) -> NumDeleted + Match the objects in an ETS table against a match_spec and deletes objects where the match_spec returns 'true' + + Tab = tid() | atom() + Object = tuple() + MatchSpec = match_spec() + NumDeleted = integer() + + +

Matches the objects in the table Tab using a + match_spec. If the + match_spec returns true for an object, that object is + removed from the table. For any other result from the + match_spec the object is retained. This is a more general + call than the ets:match_delete/2 call.

+

The function returns the number of objects actually + deleted from the table.

+ +

The match_spec has to return the atom true if + the object is to be deleted. No other return value will get the + object deleted, why one can not use the same match specification for + looking up elements as for deleting them.

+ + + + + select_count(Tab, MatchSpec) -> NumMatched + Match the objects in an ETS table against a match_spec and returns the number of objects for which the match_spec returned 'true' + + Tab = tid() | atom() + Object = tuple() + MatchSpec = match_spec() + NumMatched = integer() + + +

Matches the objects in the table Tab using a + match_spec. If the + match_spec returns true for an object, that object + considered a match and is counted. For any other result from + the match_spec the object is not considered a match and is + therefore not counted.

+

The function could be described as a match_delete/2 + that does not actually delete any elements, but only counts + them.

+

The function returns the number of objects matched.

+ + + + setopts(Tab, Opts) -> true + Set table options. + + Tab = tid() | atom() + Opts = Opt | [Opt] + Opt = {heir,pid(),HeirData} | {heir,none} + HeirData = term() + + +

Set table options. The only option that currently is allowed to be + set after the table has been created is + heir. The calling process must be + the table owner.

+ + + + slot(Tab, I) -> [Object] | '$end_of_table' + Return all objects in a given slot of an ETS table. + + Tab = tid() | atom() + I = int() + Object = tuple() + + +

This function is mostly for debugging purposes, Normally + one should use first/next or last/prev instead.

+

Returns all objects in the I:th slot of the table + Tab. A table can be traversed by repeatedly calling + the function, starting with the first slot I=0 and + ending when '$end_of_table' is returned. + The function will fail with reason badarg if the + I argument is out of range.

+

Unless a table of type set, bag or + duplicate_bag is protected using + safe_fixtable/2, see above, a traversal may fail if + concurrent updates are made to the table. If the table is of + type ordered_set, the function returns a list + containing the I:th object in Erlang term order.

+ + + + tab2file(Tab, Filename) -> ok | {error,Reason} + Dump an ETS table to a file. + + Tab = tid() | atom() + Filename = string() | atom() + Reason = term() + + +

Dumps the table Tab to the file Filename.

+

Equivalent to tab2file(Tab, Filename,[])

+ + + + + tab2file(Tab, Filename, Options) -> ok | {error,Reason} + Dump an ETS table to a file. + + Tab = tid() | atom() + Filename = string() | atom() + Options = [Option] + Option = {extended_info, [ExtInfo]} + ExtInfo = object_count | md5sum + Reason = term() + + +

Dumps the table Tab to the file Filename.

+

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 extended_info option specifies what extra + information is written to the table dump:

+ + object_count +

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.

 + md5sum +

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 extended_info option is used, it + results in a file not readable by versions of ets prior to + that in stdlib-1.15.1

+ + + + + tab2list(Tab) -> [Object] + Return a list of all objects in an ETS table. + + Tab = tid() | atom() + Object = tuple() + + +

Returns a list of all objects in the table Tab.

+ + + + tabfile_info(Filename) -> {ok, TableInfo} | {error, Reason} + Return a list of all objects in an ETS table. + + Filename = string() | atom() + TableInfo = [InfoItem] + InfoItem = {InfoTag, term()} + InfoTag = name | type | protection | named_table | keypos | size | extended_info | version + Reason = term() + + +

Returns information about the table dumped to file by + tab2file/2 or + tab2file/3

+

The following items are returned:

+ + name +

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 + file2tab/2. If the table is + not saved as a named table, this field has no significance + at all when loading the table from file.

 + type + The ets type of the dumped table (i.e. set, bag, + duplicate_bag or ordered_set). This type will be used + when loading the table again. + protection + The protection of the dumped table (i.e. private, + protected or public). A table loaded from the file + will get the same protection. + named_table + true if the table was a named table when dumped + to file, otherwise false. Note that when a named table + is loaded from a file, there cannot exist a table in the + system with the same name. + keypos + The keypos of the table dumped to file, which + will be used when loading the table again. + size + The number of objects in the table when the table dump + to file started, which in case of a public table need + not correspond to the number of objects actually saved to the + file, as objects might have been added or deleted by another + process during table dump. + extended_info + The extended information written in the file footer to + allow stronger verification during table loading from file, as + specified to tab2file/3. Note that this + function only tells which information is present, not + the values in the file footer. The value is a list containing + one or more of the atoms object_count and + md5sum. + version + A tuple {Major,Minor} containing the major and + minor version of the file format for ets table dumps. This + version field was added beginning with stdlib-1.5.1, files + dumped with older versions will return {0,0} in this + field. + +

An error is returned if the file is inaccessible, + badly damaged or not an file produced with tab2file/2 or tab2file/3.

+ + + + table(Tab [, Options]) -> QueryHandle + Return a QLC query handle. + + Tab = tid() | atom() + QueryHandle = - a query handle, see qlc(3) - + Options = [Option] | Option + Option = {n_objects, NObjects} | {traverse, TraverseMethod} + NObjects = default | integer() > 0 + TraverseMethod = first_next | last_prev | select | {select, MatchSpec} + MatchSpec = match_spec() + + +

+Returns a QLC (Query List + Comprehension) query handle. The module qlc implements + a query language aimed mainly at Mnesia but ETS tables, Dets + tables, and lists are also recognized by QLC as sources of + data. Calling ets:table/1,2 is the means to make the + ETS table Tab usable to QLC.

+

When there are only simple restrictions on the key position + QLC uses ets:lookup/2 to look up the keys, but when + that is not possible the whole table is traversed. The + option traverse determines how this is done:

+ + +

first_next. The table is traversed one key at + a time by calling ets:first/1 and + ets:next/2.

+ + +

last_prev. The table is traversed one key at + a time by calling ets:last/1 and + ets:prev/2.

+ + +

select. The table is traversed by calling + ets:select/3 and ets:select/1. The option + n_objects determines the number of objects + returned (the third argument of select/3); the + default is to return 100 objects at a time. The + match_spec (the + second argument of select/3) is assembled by QLC: + simple filters are translated into equivalent match_specs + while more complicated filters have to be applied to all + objects returned by select/3 given a match_spec + that matches all objects.

+ + +

{select, MatchSpec}. As for select + the table is traversed by calling ets:select/3 and + ets:select/1. The difference is that the + match_spec is explicitly given. This is how to state + match_specs that cannot easily be expressed within the + syntax provided by QLC.

+ + +

The following example uses an explicit match_spec 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:

+ 
+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 qlc:info/1:

+ 
+11> qlc:info(QH1) =:= qlc:info(QH2).
+true
+

qlc:info/1 returns information about a query handle, + and in this case identical information is returned for the + two query handles.

+ + + + test_ms(Tuple, MatchSpec) -> {ok, Result} | {error, Errors} + Test a match_spec for use in ets:select/2. + + Tuple = tuple() + MatchSpec = match_spec() + Result = term() + Errors = [{warning|error, string()}] + + +

This function is a utility to test a + match_spec used in + calls to ets:select/2. The function both tests + MatchSpec for "syntactic" correctness and runs the + match_spec against the object Tuple. If the match_spec + contains errors, the tuple {error, Errors} is returned + where Errors is a list of natural language + descriptions of what was wrong with the match_spec. If the + match_spec is syntactically OK, the function returns + {ok,Term} where Term is what would have been + the result in a real ets:select/2 call or false + if the match_spec does not match the object Tuple.

+

This is a useful debugging and test tool, especially when + writing complicated ets:select/2 calls.

+ + + + to_dets(Tab, DetsTab) -> Tab + Fill a Dets table with objects from an ETS table. + + Tab = tid() | atom() + DetsTab = atom() + + +

Fills an already created/opened Dets table with the objects + in the already opened ETS table named Tab. The Dets + table is emptied before the objects are inserted.

+ + + + update_counter(Tab, Key, UpdateOp) -> Result + update_counter(Tab, Key, [UpdateOp]) -> [Result] + update_counter(Tab, Key, Incr) -> Result + Update a counter object in an ETS table. + + Tab = tid() | atom() + Key = term() + UpdateOp = {Pos,Incr} | {Pos,Incr,Threshold,SetValue} + Pos = Incr = Threshold = SetValue = Result = int() + + +

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 Key + in the table Tab by adding Incr to the element + at the Pos:th position. The new counter value is + returned. If no position is specified, the element directly + following the key (+1]]>) is updated.

+

If a Threshold is specified, the counter will be + reset to the value SetValue if the following + conditions occur:

+ + The Incr is not negative (>= 0) and the + result would be greater than (>) Threshold + The Incr is negative () and the + result would be less than () + Threshold + +

A list of UpdateOp can be supplied to do several update + operations within the object. The operations are carried out in the + order specified in the list. If the same counter position occurs + more than one time in the list, the corresponding counter will thus + be updated several times, each time based on the previous result. + The return value is a list of the new counter values from each + update operation in the same order as in the operation list. If an + empty list is specified, nothing is updated and an empty list is + returned. If the function should fail, no updates will be done at + all. +

+

The given Key is used to identify the object by either + matching the key of an object in a set table, + or compare equal to the key of an object in an + ordered_set table (see + lookup/2 and + new/2 + for details on the difference).

+

The function will fail with reason badarg if:

+ + the table is not of type set or + ordered_set, + no object with the right key exists, + the object has the wrong arity, + the element to update is not an integer, + the element to update is also the key, or, + any of Pos, Incr, Threshold or + SetValue is not an integer + + + + + update_element(Tab, Key, {Pos,Value}) -> true | false + update_element(Tab, Key, [{Pos,Value}]) -> true | false + Updates the Pos:th element of the object with a given key in an ETS table. + + Tab = tid() | atom() + Key = Value = term() + Pos = int() + + +

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 Key + in the table Tab. The element at the Pos:th position + will be given the value Value.

+

A list of {Pos,Value} can be supplied to update several + elements within the same object. If the same position occurs more + than one in the list, the last value in the list will be written. If + the list is empty or the function fails, no updates will be done at + all. The function is also atomic in the sense that other processes + can never see any intermediate results. +

+

The function returns true if an object with the key + Key was found, false otherwise. +

+

The given Key is used to identify the object by either + matching the key of an object in a set table, + or compare equal to the key of an object in an + ordered_set table (see + lookup/2 and + new/2 + for details on the difference).

+

The function will fail with reason badarg if:

+ + the table is not of type set or + ordered_set, + Pos is less than 1 or greater than the object + arity, or, + the element to update is also the key + + + + + + -- cgit v1.2.3