diff options
Diffstat (limited to 'lib/erl_interface/doc/src/registry.xml')
| -rw-r--r-- | lib/erl_interface/doc/src/registry.xml | 611 |
1 files changed, 611 insertions, 0 deletions
diff --git a/lib/erl_interface/doc/src/registry.xml b/lib/erl_interface/doc/src/registry.xml new file mode 100644 index 0000000000..8aeb378d95 --- /dev/null +++ b/lib/erl_interface/doc/src/registry.xml @@ -0,0 +1,611 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE cref SYSTEM "cref.dtd"> + +<cref> + <header> + <copyright> + <year>1998</year><year>2009</year> + <holder>Ericsson AB. All Rights Reserved.</holder> + </copyright> + <legalnotice> + 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. + + </legalnotice> + + <title>registry</title> + <prepared>Gordon Beaton</prepared> + <responsible>Gordon Beaton</responsible> + <docno></docno> + <approved>Gordon Beaton</approved> + <checked>Gordon Beaton</checked> + <date>980707</date> + <rev>A</rev> + <file>registry.sgml</file> + </header> + <lib>registry</lib> + <libsummary>Store and backup key-value pairs</libsummary> + <description> + <p>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.</p> + </description> + <funcs> + <func> + <name><ret>ei_reg *</ret><nametext>ei_reg_open(size)</nametext></name> + <fsummary>Create and open a registry</fsummary> + <type> + <v>int size;</v> + </type> + <desc> + <p>Open (create) a registry. The registry will be + initially empty. Use <c><![CDATA[ei_reg_close()]]></c> to close the registry + later. + </p> + <p><c><![CDATA[size]]></c> 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 + <c><![CDATA[ei_reg_resize()]]></c> to change the size later. Note that the + number you provide will be increased to the nearest larger prime + number. + </p> + <p>On success, an empty registry will be returned. On failure, NULL + will be returned.</p> + </desc> + </func> + <func> + <name><ret>int</ret><nametext>ei_reg_resize(reg,newsize)</nametext></name> + <fsummary>Resize a registry</fsummary> + <type> + <v>ei_reg *reg;</v> + <v>int newsize;</v> + </type> + <desc> + <p>Change the size of a registry. + </p> + <p><c><![CDATA[newsize]]></c> is the new size to make the registry. The + number will be increased to the nearest larger prime number. + </p> + <p>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.</p> + </desc> + </func> + <func> + <name><ret>int</ret><nametext>ei_reg_close(reg)</nametext></name> + <fsummary>Close a registry </fsummary> + <type> + <v>ei_reg *reg;</v> + </type> + <desc> + <p>A registry that has previously been created with + <c><![CDATA[ei_reg_open()]]></c> is closed, and all the objects it contains + are freed. + </p> + <p><c><![CDATA[reg]]></c> is the registry to close. + </p> + <p>The function returns 0.</p> + </desc> + </func> + <func> + <name><ret>int</ret><nametext>ei_reg_setival(reg,key,i)</nametext></name> + <fsummary>Assign an integer object</fsummary> + <type> + <v>ei_reg *reg;</v> + <v>const char *key;</v> + <v>int i;</v> + </type> + <desc> + <p>Create a key-value pair with the specified <c><![CDATA[key]]></c> and integer + value <c><![CDATA[i]]></c>. If an object already existed with the same + <c><![CDATA[key]]></c>, the new value replaces the old one. If the previous + value was a binary or string, it is freed with <c><![CDATA[free()]]></c>. + </p> + <p><c><![CDATA[reg]]></c> is the registry where the object should be placed. + </p> + <p><c><![CDATA[key]]></c> is the name of the object. + </p> + <p><c><![CDATA[i]]></c> is the integer value to assign. + </p> + <p>The function returns 0 on success, or -1 on failure.</p> + </desc> + </func> + <func> + <name><ret>int</ret><nametext>ei_reg_setfval(reg,key,f)</nametext></name> + <fsummary>Assign a floating point object</fsummary> + <type> + <v>ei_reg *reg;</v> + <v>const char *key;</v> + <v>double f;</v> + </type> + <desc> + <p>Create a key-value pair with the specified <c><![CDATA[key]]></c> and + floating point value <c><![CDATA[f]]></c>. If an object already existed with + the same <c><![CDATA[key]]></c>, the new value replaces the old one. If the + previous value was a binary or string, it is freed with <c><![CDATA[free()]]></c>. + </p> + <p><c><![CDATA[reg]]></c> is the registry where the object should be placed. + </p> + <p><c><![CDATA[key]]></c> is the name of the object. + </p> + <p><c><![CDATA[f]]></c> is the floating point value to assign. + </p> + <p>The function returns 0 on success, or -1 on failure.</p> + </desc> + </func> + <func> + <name><ret>int</ret><nametext>ei_reg_setsval(reg,key,s)</nametext></name> + <fsummary>Assign a string object</fsummary> + <type> + <v>ei_reg *reg;</v> + <v>const char *key;</v> + <v>const char *s;</v> + </type> + <desc> + <p>Create a key-value pair with the specified <c><![CDATA[key]]></c> whose + "value" is the specified string <c><![CDATA[s]]></c>. If an object already + existed with the same <c><![CDATA[key]]></c>, the new value replaces the old + one. If the previous value was a binary or string, it is freed + with <c><![CDATA[free()]]></c>. + </p> + <p><c><![CDATA[reg]]></c> is the registry where the object should be placed. + </p> + <p><c><![CDATA[key]]></c> is the name of the object. + </p> + <p><c><![CDATA[s]]></c> is the string to assign. The string itself + must have been created through a single call to <c><![CDATA[malloc()]]></c> or + similar function, so that the registry can later delete it if + necessary by calling <c><![CDATA[free()]]></c>. + </p> + <p>The function returns 0 on success, or -1 on failure.</p> + </desc> + </func> + <func> + <name><ret>int</ret><nametext>ei_reg_setpval(reg,key,p,size)</nametext></name> + <fsummary>Assign a binary object</fsummary> + <type> + <v>ei_reg *reg;</v> + <v>const char *key;</v> + <v>const void *p;</v> + <v>int size;</v> + </type> + <desc> + <p>Create a key-value pair with the specified <c><![CDATA[key]]></c> whose + "value" is the binary object pointed to by <c><![CDATA[p]]></c>. If an + object already existed with the same <c><![CDATA[key]]></c>, the new value + replaces the old one. If the previous value was a binary or + string, it is freed with <c><![CDATA[free()]]></c>. + </p> + <p><c><![CDATA[reg]]></c> is the registry where the object should be placed. + </p> + <p><c><![CDATA[key]]></c> is the name of the object. + </p> + <p><c><![CDATA[p]]></c> is a pointer to the binary object. The object itself + must have been created through a single call to <c><![CDATA[malloc()]]></c> or + similar function, so that the registry can later delete it if + necessary by calling <c><![CDATA[free()]]></c>. + </p> + <p><c><![CDATA[size]]></c> is the length in bytes of the binary object. + </p> + <p>The function returns 0 on success, or -1 on failure.</p> + </desc> + </func> + <func> + <name><ret>int</ret><nametext>ei_reg_setval(reg,key,flags,v,...)</nametext></name> + <fsummary>Assign a value to any object type</fsummary> + <type> + <v>ei_reg *reg;</v> + <v>const char *key;</v> + <v>int flags;</v> + <v>v (see below)</v> + </type> + <desc> + <p>Create a key-value pair with the specified <c><![CDATA[key]]></c> whose + value is specified by <c><![CDATA[v]]></c>. If an object already + existed with the same <c><![CDATA[key]]></c>, the new value replaces the old + one. If the previous value was a binary or string, it is freed + with <c><![CDATA[free()]]></c>. + </p> + <p><c><![CDATA[reg]]></c> is the registry where the object should be placed. + </p> + <p><c><![CDATA[key]]></c> is the name of the object. + </p> + <p><c><![CDATA[flags]]></c> indicates the type of the object specified by + <c><![CDATA[v]]></c>. Flags must be one of EI_INT, EI_FLT, EI_STR and + EI_BIN, indicating whether <c><![CDATA[v]]></c> is <c><![CDATA[int]]></c>, <c><![CDATA[double]]></c>, + <c><![CDATA[char*]]></c> or <c><![CDATA[void*]]></c>. If <c><![CDATA[flags]]></c> is EI_BIN, then a + fifth argument <c><![CDATA[size]]></c> is required, indicating the size + in bytes of the object pointed to by <c><![CDATA[v]]></c>. + </p> + <p>If you wish to store an arbitrary pointer in the registry, + specify a <c><![CDATA[size]]></c> of 0. In this case, the object itself will + not be transferred by an <c><![CDATA[ei_reg_dump()]]></c> operation, just + the pointer value. + </p> + <p>The function returns 0 on success, or -1 on failure.</p> + </desc> + </func> + <func> + <name><ret>int</ret><nametext>ei_reg_getival(reg,key)</nametext></name> + <fsummary>Get an integer object</fsummary> + <type> + <v>ei_reg *reg;</v> + <v>const char *key;</v> + </type> + <desc> + <p>Get the value associated with <c><![CDATA[key]]></c> in the + registry. The value must be an integer. + </p> + <p><c><![CDATA[reg]]></c> is the registry where the object will be looked + up. + </p> + <p><c><![CDATA[key]]></c> is the name of the object to look up. + </p> + <p>On success, the function returns the value associated with <c><![CDATA[key]]></c>. + 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 <c><![CDATA[ei_reg_getval()]]></c> + instead.</p> + </desc> + </func> + <func> + <name><ret>double</ret><nametext>ei_reg_getfval(reg,key)</nametext></name> + <fsummary>Get a floating point object</fsummary> + <type> + <v>ei_reg *reg;</v> + <v>const char *key;</v> + </type> + <desc> + <p>Get the value associated with <c><![CDATA[key]]></c> in the + registry. The value must be a floating point type. + </p> + <p><c><![CDATA[reg]]></c> is the registry where the object will be looked + up. + </p> + <p><c><![CDATA[key]]></c> is the name of the object to look up. + </p> + <p>On success, the function returns the value associated with <c><![CDATA[key]]></c>. + 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 <c><![CDATA[ei_reg_getval()]]></c> + instead.</p> + </desc> + </func> + <func> + <name><ret>const char *</ret><nametext>ei_reg_getsval(reg,key)</nametext></name> + <fsummary>Get a string object</fsummary> + <type> + <v>ei_reg *reg;</v> + <v>const char *key;</v> + </type> + <desc> + <p>Get the value associated with <c><![CDATA[key]]></c> in the + registry. The value must be a string. + </p> + <p><c><![CDATA[reg]]></c> is the registry where the object will be looked + up. + </p> + <p><c><![CDATA[key]]></c> is the name of the object to look up. + </p> + <p>On success, the function returns the value associated with + <c><![CDATA[key]]></c>. 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 <c><![CDATA[ei_reg_getval()]]></c> + instead.</p> + </desc> + </func> + <func> + <name><ret>const void *</ret><nametext>ei_reg_getpval(reg,key,size)</nametext></name> + <fsummary>Get a binary object</fsummary> + <type> + <v>ei_reg *reg;</v> + <v>const char *key;</v> + <v>int size;</v> + </type> + <desc> + <p>Get the value associated with <c><![CDATA[key]]></c> in the + registry. The value must be a binary (pointer) type. + </p> + <p><c><![CDATA[reg]]></c> is the registry where the object will be looked + up. + </p> + <p><c><![CDATA[key]]></c> is the name of the object to look up. + </p> + <p><c><![CDATA[size]]></c> will be initialized to contain the length in + bytes of the object, if it is found. + </p> + <p>On success, the function returns the value associated with + <c><![CDATA[key]]></c> and indicates its length in <c><![CDATA[size]]></c>. + 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 <c><![CDATA[ei_reg_getval()]]></c> + instead.</p> + </desc> + </func> + <func> + <name><ret>int</ret><nametext>ei_reg_getval(reg,key,flags,v,...)</nametext></name> + <fsummary>Get any object</fsummary> + <type> + <v>ei_reg *reg;</v> + <v>const char *key;</v> + <v>int flags;</v> + <v>void *v (see below)</v> + </type> + <desc> + <p>This is a general function for retrieving any kind of + object from the registry. + </p> + <p><c><![CDATA[reg]]></c> is the registry where the object will be looked + up. + </p> + <p><c><![CDATA[key]]></c> is the name of the object to look up. + </p> + <p><c><![CDATA[flags]]></c> indicates the type of object that you are + looking for. If <c><![CDATA[flags]]></c> is 0, then any kind of object will + be returned. If <c><![CDATA[flags]]></c> 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 <c><![CDATA[v]]></c> must be large enough to hold the return + data, i.e. it must be a pointer to one of <c><![CDATA[int]]></c>, + <c><![CDATA[double]]></c>, <c><![CDATA[char*]]></c> or <c><![CDATA[void*]]></c>, respectively. Also, + if <c><![CDATA[flags]]></c> is EI_BIN, then a fifth argument <c><![CDATA[int *size]]></c> is required, so that the size of the object can be + returned. + </p> + <p>If the function succeeds, <c><![CDATA[v]]></c> (and <c><![CDATA[size]]></c> if the + object is binary) will be initialized with the value associated + with <c><![CDATA[key]]></c>, 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.</p> + </desc> + </func> + <func> + <name><ret>int</ret><nametext>ei_reg_markdirty(reg,key)</nametext></name> + <fsummary>Mark an object as dirty </fsummary> + <type> + <v>ei_reg *reg;</v> + <v>const char *key;</v> + </type> + <desc> + <p>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. + </p> + <p><c><![CDATA[reg]]></c> is the registry containing the object. + </p> + <p><c><![CDATA[key]]></c> is the name of the object to mark. + </p> + <p>The function returns 0 on success, or -1 on failure.</p> + </desc> + </func> + <func> + <name><ret>int</ret><nametext>ei_reg_delete(reg,key)</nametext></name> + <fsummary>Delete an object from the registry</fsummary> + <type> + <v>ei_reg *reg;</v> + <v>const char *key;</v> + </type> + <desc> + <p>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. + </p> + <p>The object will be removed from the registry after a call to + <c><![CDATA[ei_reg_dump()]]></c> or <c><![CDATA[ei_reg_purge()]]></c>. + </p> + <p><c><![CDATA[reg]]></c> is the registry containing <c><![CDATA[key]]></c>. + </p> + <p><c><![CDATA[key]]></c> is the object to remove. + </p> + <p>If the object was found, the function returns 0 indicating + success. Otherwise the function returns -1.</p> + </desc> + </func> + <func> + <name><ret>int</ret><nametext>ei_reg_stat(reg,key,obuf)</nametext></name> + <fsummary>Get object information</fsummary> + <type> + <v>ei_reg *reg;</v> + <v>const char *key;</v> + <v>struct ei_reg_stat *obuf;</v> + </type> + <desc> + <p>Return information about an object. + </p> + <p><c><![CDATA[reg]]></c> is the registry containing the object. + </p> + <p><c><![CDATA[key]]></c> is the name of the object. + </p> + <p><c><![CDATA[obuf]]></c> is a pointer to an <c><![CDATA[ei_reg_stat]]></c> structure, + defined below: + </p> + <code type="none"><![CDATA[ +struct ei_reg_stat { + int attr; + int size; +}; + ]]></code> + <p>In <c><![CDATA[attr]]></c> 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). + </p> + <p>The <c><![CDATA[size]]></c> 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. + </p> + <p>The function returns 0 and initializes <c><![CDATA[obuf]]></c> on + success, or returns -1 on failure.</p> + </desc> + </func> + <func> + <name><ret>int</ret><nametext>ei_reg_tabstat(reg,obuf)</nametext></name> + <fsummary>Get registry information</fsummary> + <type> + <v>ei_reg *reg;</v> + <v>struct ei_reg_tabstat *obuf;</v> + </type> + <desc> + <p>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. + </p> + <p><c><![CDATA[reg]]></c> is the registry to return information about. + </p> + <p><c><![CDATA[obuf]]></c> is a pointer to an <c><![CDATA[ei_reg_tabstat]]></c> structure, + defined below: + </p> + <code type="none"><![CDATA[ +struct ei_reg_tabstat { + int size; + int nelem; + int npos; + int collisions; +}; + ]]></code> + <p>The <c><![CDATA[size]]></c> 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. + </p> + <p><c><![CDATA[nelem]]></c> indicates the number of elements stored in the + registry. It includes objects that are deleted but not purged. + </p> + <p><c><![CDATA[npos]]></c> indicates the number of unique positions that are + occupied in the registry. + </p> + <p><c><![CDATA[collisions]]></c> indicates how many elements are sharing + positions in the registry. + </p> + <p>On success, the function returns 0 and <c><![CDATA[obuf]]></c> is + initialized to contain table statistics. On failure, the function + returns -1.</p> + </desc> + </func> + <func> + <name><ret>int</ret><nametext>ei_reg_dump(fd,reg,mntab,flags)</nametext></name> + <fsummary>Back up a registry to Mnesia</fsummary> + <type> + <v>int fd;</v> + <v>ei_reg *reg;</v> + <v>const char *mntab;</v> + <v>int flags;</v> + </type> + <desc> + <p>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. + </p> + <p><c><![CDATA[fd]]></c> is an open connection to Erlang. + Mnesia 3.0 or later must be running on the Erlang node. + </p> + <p><c><![CDATA[reg]]></c> is the registry to back up. + </p> + <p><c><![CDATA[mntab]]></c> 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. + </p> + <p>If <c><![CDATA[flags]]></c> 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. + </p> + <p>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 <c><![CDATA[ei_reg_purge()]]></c> to explicitly remove + the deleted items from the registry later. + </p> + <p>The function returns 0 on success, or -1 on failure.</p> + </desc> + </func> + <func> + <name><ret>int</ret><nametext>ei_reg_restore(fd,reg,mntab)</nametext></name> + <fsummary>Restore a registry from Mnesia</fsummary> + <type> + <v>int fd;</v> + <v>ei_reg *reg;</v> + <v>const char *mntab;</v> + </type> + <desc> + <p>The contents of a Mnesia table are read into the + registry. + </p> + <p><c><![CDATA[fd]]></c> is an open connection to Erlang. + Mnesia 3.0 or later must be running on the Erlang node. + </p> + <p><c><![CDATA[reg]]></c> is the registry where the data should be placed. + </p> + <p><c><![CDATA[mntab]]></c> is the name of the Mnesia table to read data + from. + </p> + <p>Note that only tables of a certain format can be + restored, i.e. those that have been created and backed up to + with <c><![CDATA[ei_reg_dump()]]></c>. 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. + </p> + <p>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. + </p> + <p>The function returns 0 on success, or -1 on failure.</p> + </desc> + </func> + <func> + <name><ret>int</ret><nametext>ei_reg_purge(reg)</nametext></name> + <fsummary>Remove deleted objects</fsummary> + <type> + <v>ei_reg *reg;</v> + </type> + <desc> + <p>Remove all objects marked for deletion. When objects + are deleted with <c><![CDATA[ei_reg_delete()]]></c> 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. + </p> + <p><c><![CDATA[reg]]></c> is a registry containing objects marked for + deletion. + </p> + <p>The function returns 0 on success, or -1 on failure.</p> + </desc> + </func> + </funcs> +</cref> + |