Provided by: erlang-manpages_16.b.3-dfsg-1ubuntu2_all bug

NAME

       registry - Store and backup key-value pairs

DESCRIPTION

       This  module  provides support for storing key-value pairs in a table known as a registry,
       backing up registries to Mnesia in an atomic manner, and later restoring the contents of a
       registry from Mnesia.

EXPORTS

       ei_reg *ei_reg_open(size)

              Types:

                 int size;

              Open  (create) a registry. The registry will be initially empty. Use ei_reg_close()
              to close the registry later.

              size is the approximate number of objects you intend  to  store  in  the  registry.
              Since  the registry uses a hash table with collision chaining, there is no absolute
              upper limit on the number of objects that can be stored in it. However for  reasons
              of  efficiency,  it  is a good idea to choose a number that is appropriate for your
              needs. It is possible to use ei_reg_resize() to change the size  later.  Note  that
              the number you provide will be increased to the nearest larger prime number.

              On success, an empty registry will be returned. On failure, NULL will be returned.

       int ei_reg_resize(reg,newsize)

              Types:

                 ei_reg *reg;
                 int newsize;

              Change the size of a registry.

              newsize  is  the new size to make the registry. The number will be increased to the
              nearest larger prime number.

              On success, the registry will be resized, all contents rehashed, and  the  function
              will  return  0.  On  failure, the registry will be left unchanged and the function
              will return -1.

       int ei_reg_close(reg)

              Types:

                 ei_reg *reg;

              A registry that has previously been created with ei_reg_open() is closed,  and  all
              the objects it contains are freed.

              reg is the registry to close.

              The function returns 0.

       int ei_reg_setival(reg,key,i)

              Types:

                 ei_reg *reg;
                 const char *key;
                 int i;

              Create  a  key-value  pair with the specified key and integer value i. If an object
              already existed with the same key, the new value  replaces  the  old  one.  If  the
              previous value was a binary or string, it is freed with free().

              reg is the registry where the object should be placed.

              key is the name of the object.

              i is the integer value to assign.

              The function returns 0 on success, or -1 on failure.

       int ei_reg_setfval(reg,key,f)

              Types:

                 ei_reg *reg;
                 const char *key;
                 double f;

              Create  a  key-value  pair with the specified key and floating point value f. If an
              object already existed with the same key, the new value replaces the  old  one.  If
              the previous value was a binary or string, it is freed with free().

              reg is the registry where the object should be placed.

              key is the name of the object.

              f is the floating point value to assign.

              The function returns 0 on success, or -1 on failure.

       int ei_reg_setsval(reg,key,s)

              Types:

                 ei_reg *reg;
                 const char *key;
                 const char *s;

              Create  a  key-value  pair  with  the  specified key whose "value" is the specified
              string s. If an object already existed with the same key, the  new  value  replaces
              the old one. If the previous value was a binary or string, it is freed with free().

              reg is the registry where the object should be placed.

              key is the name of the object.

              s  is  the  string  to  assign.  The string itself must have been created through a
              single call to malloc() or similar function, so that the registry can later  delete
              it if necessary by calling free().

              The function returns 0 on success, or -1 on failure.

       int ei_reg_setpval(reg,key,p,size)

              Types:

                 ei_reg *reg;
                 const char *key;
                 const void *p;
                 int size;

              Create  a  key-value pair with the specified key whose "value" is the binary object
              pointed to by p. If an object already existed with the  same  key,  the  new  value
              replaces  the  old  one.  If the previous value was a binary or string, it is freed
              with free().

              reg is the registry where the object should be placed.

              key is the name of the object.

              p is a pointer to the binary object. The  object  itself  must  have  been  created
              through  a  single  call  to malloc() or similar function, so that the registry can
              later delete it if necessary by calling free().

              size is the length in bytes of the binary object.

              The function returns 0 on success, or -1 on failure.

       int ei_reg_setval(reg,key,flags,v,...)

              Types:

                 ei_reg *reg;
                 const char *key;
                 int flags;
                 v (see below)

              Create a key-value pair with the specified key whose value is specified by v. If an
              object  already  existed  with the same key, the new value replaces the old one. If
              the previous value was a binary or string, it is freed with free().

              reg is the registry where the object should be placed.

              key is the name of the object.

              flags indicates the type of the object specified by v. Flags must be one of EI_INT,
              EI_FLT,  EI_STR and EI_BIN, indicating whether v is int, double, char* or void*. If
              flags is EI_BIN, then a fifth argument size is required,  indicating  the  size  in
              bytes of the object pointed to by v.

              If  you wish to store an arbitrary pointer in the registry, specify a size of 0. In
              this case, the object itself will not be transferred by an ei_reg_dump() operation,
              just the pointer value.

              The function returns 0 on success, or -1 on failure.

       int ei_reg_getival(reg,key)

              Types:

                 ei_reg *reg;
                 const char *key;

              Get the value associated with key in the registry. The value must be an integer.

              reg is the registry where the object will be looked up.

              key is the name of the object to look up.

              On  success,  the function returns the value associated with key. If the object was
              not found or it was not an integer object, -1 is returned. To avoid  problems  with
              in-band  error  reporting  (i.e.  if  you cannot distinguish between -1 and a valid
              result) use the more general function ei_reg_getval() instead.

       double ei_reg_getfval(reg,key)

              Types:

                 ei_reg *reg;
                 const char *key;

              Get the value associated with key in the registry. The value  must  be  a  floating
              point type.

              reg is the registry where the object will be looked up.

              key is the name of the object to look up.

              On  success,  the function returns the value associated with key. If the object was
              not found or it was not a  floating  point  object,  -1.0  is  returned.  To  avoid
              problems  with in-band error reporting (i.e. if you cannot distinguish between -1.0
              and a valid result) use the more general function ei_reg_getval() instead.

       const char *ei_reg_getsval(reg,key)

              Types:

                 ei_reg *reg;
                 const char *key;

              Get the value associated with key in the registry. The value must be a string.

              reg is the registry where the object will be looked up.

              key is the name of the object to look up.

              On success, the function returns the value associated with key. If the  object  was
              not  found or it was not a string, NULL is returned. To avoid problems with in-band
              error reporting (i.e. if you cannot distinguish between NULL and  a  valid  result)
              use the more general function ei_reg_getval() instead.

       const void *ei_reg_getpval(reg,key,size)

              Types:

                 ei_reg *reg;
                 const char *key;
                 int size;

              Get  the  value  associated  with  key  in the registry. The value must be a binary
              (pointer) type.

              reg is the registry where the object will be looked up.

              key is the name of the object to look up.

              size will be initialized to contain the length in bytes of the  object,  if  it  is
              found.

              On  success,  the  function returns the value associated with key and indicates its
              length in size. If the object was not found or it was not a binary object, NULL  is
              returned.  To  avoid  problems  with  in-band  error  reporting (i.e. if you cannot
              distinguish between NULL  and  a  valid  result)  use  the  more  general  function
              ei_reg_getval() instead.

       int ei_reg_getval(reg,key,flags,v,...)

              Types:

                 ei_reg *reg;
                 const char *key;
                 int flags;
                 void *v (see below)

              This is a general function for retrieving any kind of object from the registry.

              reg is the registry where the object will be looked up.

              key is the name of the object to look up.

              flags  indicates  the  type of object that you are looking for. If flags is 0, then
              any kind of object will be returned. If flags is one of EI_INT, EI_FLT,  EI_STR  or
              EI_BIN,  then only values of that kind will be returned. The buffer pointed to by v
              must be large enough to hold the return data, i.e. it must be a pointer to  one  of
              int,  double,  char* or void*, respectively. Also, if flags is EI_BIN, then a fifth
              argument int *size is required, so that the size of the object can be returned.

              If the function succeeds, v (and size if the object is binary) will be  initialized
              with  the  value  associated  with key, and the function will return one of EI_INT,
              EI_FLT, EI_STR or EI_BIN, indicating the type of object. On  failure  the  function
              will return -1 and the arguments will not be updated.

       int ei_reg_markdirty(reg,key)

              Types:

                 ei_reg *reg;
                 const char *key;

              Mark  a  registry object as dirty. This will ensure that it is included in the next
              backup to Mnesia. Normally this operation will not be necessary since  all  of  the
              normal  registry  'set'  functions  do  this  automatically.  However  if  you have
              retrieved the value of a string or binary object from the registry and modified the
              contents,  then the change will be invisible to the registry and the object will be
              assumed to be unmodified. This function allows you to make such  modifications  and
              then let the registry know about them.

              reg is the registry containing the object.

              key is the name of the object to mark.

              The function returns 0 on success, or -1 on failure.

       int ei_reg_delete(reg,key)

              Types:

                 ei_reg *reg;
                 const char *key;

              Delete  an  object  from  the registry. The object is not actually removed from the
              registry, it is only marked for later removal so  that  on  subsequent  backups  to
              Mnesia,  the  corresponding object can be removed from the Mnesia table as well. If
              another object is later created with the same key, the object will be reused.

              The object will be removed from the registry  after  a  call  to  ei_reg_dump()  or
              ei_reg_purge().

              reg is the registry containing key.

              key is the object to remove.

              If  the  object was found, the function returns 0 indicating success. Otherwise the
              function returns -1.

       int ei_reg_stat(reg,key,obuf)

              Types:

                 ei_reg *reg;
                 const char *key;
                 struct ei_reg_stat *obuf;

              Return information about an object.

              reg is the registry containing the object.

              key is the name of the object.

              obuf is a pointer to an ei_reg_stat structure, defined below:

              struct ei_reg_stat {
                int attr;
                int size;
              };

              In attr the object's attributes are stored as the logical OR of its  type  (one  of
              EI_INT,  EI_FLT,  EI_BIN  and EI_STR), whether it is marked for deletion (EI_DELET)
              and whether it has been modified since the last backup to Mnesia (EI_DIRTY).

              The size field indicates the size in bytes required to store EI_STR (including  the
              terminating 0) and EI_BIN objects, or 0 for EI_INT and EI_FLT.

              The function returns 0 and initializes obuf on success, or returns -1 on failure.

       int ei_reg_tabstat(reg,obuf)

              Types:

                 ei_reg *reg;
                 struct ei_reg_tabstat *obuf;

              Return  information  about a registry. Using information returned by this function,
              you can see whether the size of the registry is suitable for the amount of data  it
              contains.

              reg is the registry to return information about.

              obuf is a pointer to an ei_reg_tabstat structure, defined below:

              struct ei_reg_tabstat {
                int size;
                int nelem;
                int npos;
                int collisions;
              };

              The  size field indicates the number of hash positions in the registry. This is the
              number you provided when you created or last resized the registry,  rounded  up  to
              the nearest prime.

              nelem  indicates the number of elements stored in the registry. It includes objects
              that are deleted but not purged.

              npos indicates the number of unique positions that are occupied in the registry.

              collisions indicates how many elements are sharing positions in the registry.

              On success, the function returns  0  and  obuf  is  initialized  to  contain  table
              statistics. On failure, the function returns -1.

       int ei_reg_dump(fd,reg,mntab,flags)

              Types:

                 int fd;
                 ei_reg *reg;
                 const char *mntab;
                 int flags;

              Dump  the contents of a registry to a Mnesia table in an atomic manner, i.e. either
              all data will be updated, or none of it will. If any errors are  encountered  while
              backing up the data, the entire operation is aborted.

              fd  is  an  open  connection  to Erlang. Mnesia 3.0 or later must be running on the
              Erlang node.

              reg is the registry to back up.

              mntab is the name of the Mnesia table where the backed up data should be placed. If
              the  table  does  not  exist,  it  will be created automatically using configurable
              defaults. See your Mnesia documentation  for  information  about  configuring  this
              behaviour.

              If  flags is 0, the backup will include only those objects which have been created,
              modified or deleted since the last backup or restore (i.e. an incremental  backup).
              After the backup, any objects that were marked dirty are now clean, and any objects
              that had been marked for deletion are deleted.

              Alternatively, setting flags to EI_FORCE will cause a full backup to be  done,  and
              EI_NOPURGE  will  cause  the deleted objects to be left in the registry afterwards.
              These can be bitwise ORed together if both behaviours are  desired.  If  EI_NOPURGE
              was  specified,  you  can use ei_reg_purge() to explicitly remove the deleted items
              from the registry later.

              The function returns 0 on success, or -1 on failure.

       int ei_reg_restore(fd,reg,mntab)

              Types:

                 int fd;
                 ei_reg *reg;
                 const char *mntab;

              The contents of a Mnesia table are read into the registry.

              fd is an open connection to Erlang. Mnesia 3.0 or later  must  be  running  on  the
              Erlang node.

              reg is the registry where the data should be placed.

              mntab is the name of the Mnesia table to read data from.

              Note  that  only  tables  of a certain format can be restored, i.e. those that have
              been created and backed up to with ei_reg_dump(). If the  registry  was  not  empty
              before  the  operation, then the contents of the table are added to the contents of
              the registry. If the table contains objects with the same keys as those already  in
              the  registry, the registry objects will be overwritten with the new values. If the
              registry contains objects that were not in the table, they  will  be  unchanged  by
              this operation.

              After  the  restore  operation,  the  entire  contents of the registry is marked as
              unmodified. Note that this includes any  objects  that  were  modified  before  the
              restore and not overwritten by the restore.

              The function returns 0 on success, or -1 on failure.

       int ei_reg_purge(reg)

              Types:

                 ei_reg *reg;

              Remove   all   objects   marked   for  deletion.  When  objects  are  deleted  with
              ei_reg_delete() they are not actually removed from the registry,  only  marked  for
              later  removal.  This  is so that on a subsequent backup to Mnesia, the objects can
              also be removed from the Mnesia table. If you are not backing up to Mnesia then you
              may wish to remove the objects manually with this function.

              reg is a registry containing objects marked for deletion.

              The function returns 0 on success, or -1 on failure.