Unix/Linux Go Back    


Linux 2.6 - man page for ets (linux section 3erl)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


ets(3erl)			     Erlang Module Definition				ets(3erl)

NAME
       ets - Built-In Term Storage

DESCRIPTION
       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  cre-
       ated  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 refer-
       ences 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 . The  default  owner
       is  the process that created the table. Table ownership can be transferred at process ter-
       mination 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.

FAILURE
       In  general,  the  functions  below will exit with reason badarg if any argument is of the
       wrong format, if the table identifier is invalid or if the operation is denied due to  ta-
       ble access rights ( protected or private ).

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 opera-
       tion  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) simulta-
       neously deletes or inserts objects into the table. Nothing more is guaranteed; in particu-
       lar  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

EXPORTS
       all() -> [Tab]

	      Types  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

	      Types  Tab = tid() | atom()

	      Deletes the entire table Tab .

       delete(Tab, Key) -> true

	      Types  Tab = tid() | atom()
		     Key = term()

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

       delete_all_objects(Tab) -> true

	      Types  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

	      Types  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}

	      Types  Filename = string() | atom()
		     Tab = tid() | atom()
		     Reason = term()

	      Reads a file produced by tab2file/2 or tab2file/3 and creates the corresponding ta-
	      ble Tab .

	      Equivalent to file2tab(Filename,[]) .

       file2tab(Filename,Options) -> {ok,Tab} | {error,Reason}

	      Types  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 ta-
	      ble Tab .

	      The  currently only supported option is {verify,bool()} . If verification is turned
	      on (by means of specifying {verify,true} ), the function utilizes whatever informa-
	      tion 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 num-
	      ber  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 informa-
	      tion 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'

	      Types  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

	      Types  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 traver-
	      sal.

       foldr(Function, Acc0, Tab) -> Acc1

	      Types  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 traver-
	      sal.

       from_dets(Tab, DetsTab) -> true

	      Types  Tab = tid() | atom()
		     DetsTab = atom()

	      Fills  an already created ETS table with the objects in the already opened Dets ta-
	      ble named DetsTab . The existing objects of the ETS table are kept unless overwrit-
	      ten.

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

       fun2ms(LiteralFun) -> MatchSpec

	      Types  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. Fail-
	      ing  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.  Lan-
	      guage  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).

   Warning:
       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(3erl) .

       give_away(Tab, Pid, GiftData) -> true

	      Types  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

	      Displays information about all ETS tables on tty.

       i(Tab) -> ok

	      Types  Tab = tid() | atom()

	      Browses the table Tab on tty.

       info(Tab) -> [{Item, Value}] | undefined

	      Types  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.

		* Item=compressed, Value=true|false
		  Indicates if the table is compressed or not.

       info(Tab, Item) -> Value | undefined

	      Types  Tab = tid() | atom()
		     Item, Value - see below

	      Returns the information associated with Item for the table Tab , or  returns  unde-
	      fined  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 .

   Warning:
       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, keep-
	   ing 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

	      Types  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

	      Types  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 hap-
	      pen 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()

	      Types  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 func-
	      tion 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()

	      Types  Term = term()

	      This function is used to check if a term is a valid compiled match_spec . The  com-
	      piled  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  com-
	      piled  match_spec  will result in an empty binary ( <<>> ). As an example, the fol-
	      lowing 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.

   Note:
       The  fact that compiled match_specs has no external representation is for performance rea-
       sons. 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'

	      Types  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]

	      Types  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 how-
	      ever, 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 con-
	      stant, 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

	      Types  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 com-
	      pare  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]

	      Types  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'

	      Types  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'

	      Types  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

	      Types  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]

	      Types  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'

	      Types  Tab = tid() | atom()
		     Pattern = tuple()
		     Match = [term()]
		     Continuation = term()

	      Works like ets:match_object/2 but only returns a limited ( Limit ) number of match-
	      ing  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 effi-
	      cient  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'

	      Types  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 Con-
	      tinuation 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

	      Types  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 valid-
	      ity 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.

   Note:
       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()

	      Types  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),

   Note:
       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

	      Types  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()

	      Types  Name = atom()
		     Options = [Option]
		     Option = Type | Access | named_table | {keypos,Pos} |  {heir,pid(),HeirData}
		     | {heir,none} | Tweaks
		     Type = set | ordered_set | bag | duplicate_bag
		     Access = public | protected | private
		     Tweaks = {write_concurrency,bool()} | {read_concurrency,bool()} | compressed
		     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_concur-
	      rency,false},{read_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 ta-
		  ble 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  ele-
		  ments.

		*

		  {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 , in which case
		  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 sequential access and concurrent
		  reader performance. The write_concurrency  option  can  be  combined	with  the
		  read_concurrency option. You typically want to combine these when large concur-
		  rent read bursts and large concurrent write bursts are common (see the documen-
		  tation  of  the  read_concurrency  option for more information). 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  implementa-
		  tion.

		*

		  {read_concurrency,bool()}  Performance  tuning.  Default is false . When set to
		  true , the table is optimized for concurrent read operations. When this  option
		  is  enabled  on  a runtime system with SMP support, read operations become much
		  cheaper; especially on systems  with	multiple  physical  processors.  However,
		  switching  between  read and write operations becomes more expensive. You typi-
		  cally 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 (i.e., lots of reads not interrupted by writes, and
		  lots	of  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 will get a performance
		  degradation by enabling this option. The read_concurrency option  can  be  com-
		  bined  with  the  write_concurrency option. You typically want to combine these
		  when large concurrent read bursts and large concurrent write bursts are common.

		*

		  compressed If this option is present, the table data will be stored in  a  more
		  compact  format to consume less memory. The downside is that it will make table
		  operations slower. Especially operations that need to inspect  entire  objects,
		  such	as  match  and select , will get much slower. The key element is not com-
		  pressed in current implementation.

       next(Tab, Key1) -> Key2 | '$end_of_table'

	      Types  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'

	      Types  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

	      Types  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

	      Types  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 .

   Note:
       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 perfor-
       mance. It may be subject to change in future releases, while this  interface  will  remain
       for backward compatibility.

       safe_fixtable(Tab, true|false) -> true

	      Types  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]

	      Types  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  con-
	      structed,  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(3erl)
	      ).

	      The Guard s 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 ta-
	      ble 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 writ-
	      ten with the same syntax as the guard tests (prefix notation), so that a guard test
	      written in Erlang looking like this:

	      is_integer(X), is_integer(Y), X + Y < 4711

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

	      [{is_integer, '$1'}, {is_integer, '$2'}, {'<', {'+', '$1', '$2'}, 4711}]

	      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'

	      Types  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'

	      Types  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_count(Tab, MatchSpec) -> NumMatched

	      Types  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.

       select_delete(Tab, MatchSpec) -> NumDeleted

	      Types  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.

   Note:
       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_reverse(Tab, MatchSpec) -> [Match]

	      Types  Tab = tid() | atom()
		     Match = term()
		     MatchSpec = match_spec()

	      Works like select/2 , but returns the list in reverse order for the ordered_set ta-
	      ble  type.  For  all  other  table  types, the return value is identical to that of
	      select/2 .

       select_reverse(Tab, MatchSpec, Limit) -> {[Match],Continuation} | '$end_of_table'

	      Types  Tab = tid() | atom()
		     Match = term()
		     MatchSpec = match_spec()
		     Continuation = term()

	      Works like select/3 , but for the ordered_set table type, traversing is done start-
	      ing  at  the  last object in Erlang term order and moves towards the first. For all
	      other table types, the return value is identical to that of select/3 .

	      Note that this is not equivalent to reversing the result list of a  select/3  call,
	      as  the result list is not only reversed, but also contains the last Limit matching
	      objects in the table, not the first.

       select_reverse(Continuation) -> {[Match],Continuation} | '$end_of_table'

	      Types  Match = term()
		     Continuation = term()

	      Continues  a  match  started  with  ets:select_reverse/3	.  If  the  table  is  an
	      ordered_set  ,  the  traversal of the table will continue towards objects with keys
	      earlier in the Erlang term order. The returned list will also contain objects  with
	      keys in reverse order.

	      For all other table types, the behaviour is exatly that of select/1 .

	      Example:

	      1> T = ets:new(x,[ordered_set]).
	      2> [ ets:insert(T,{N}) || N <- lists:seq(1,10) ].
	      3> {R0,C0} = ets:select_reverse(T,[{'_',[],['$_']}],4).
	      4> R0.
	      [{10},{9},{8},{7}]
	      5> {R1,C1} = ets:select_reverse(C0).
	      6> R1.
	      [{6},{5},{4},{3}]
	      7> {R2,C2} = ets:select_reverse(C1).
	      8> R2.
	      [{2},{1}]
	      9> '$end_of_table' = ets:select_reverse(C2).

       setopts(Tab, Opts) -> true

	      Types  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'

	      Types  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  con-
	      taining the I :th object in Erlang term order.

       tab2file(Tab, Filename) -> ok | {error,Reason}

	      Types  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}

	      Types  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 verifi-
	      cation 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 func-
		  tions.  The MD5 sum of all objects is written in the file footer, so that veri-
		  fication 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]

	      Types  Tab = tid() | atom()
		     Object = tuple()

	      Returns a list of all objects in the table Tab .

       tabfile_info(Filename) -> {ok, TableInfo} | {error, Reason}

	      Types  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 ta-
		  ble 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 ta-
		  ble 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 verifica-
		  tion	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 pro-
	      duced with tab2file/2 or tab2file/3 .

       table(Tab [, Options]) -> QueryHandle

	      Types  Tab = tid() | atom()
		     QueryHandle = - a query handle, see qlc(3erl) -
		     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}

	      Types  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) -> DetsTab

	      Types  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

	      Types  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 atomi-
	      cally; 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 ( <keypos>+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 ( < 0 ) 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

	      Types  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

Ericsson AB				  stdlib 1.17.3 				ets(3erl)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 10:57 AM.