diff options
Diffstat (limited to 'lib/erl_interface/doc/src/registry.xml')
| -rw-r--r-- | lib/erl_interface/doc/src/registry.xml | 869 |
1 files changed, 447 insertions, 422 deletions
diff --git a/lib/erl_interface/doc/src/registry.xml b/lib/erl_interface/doc/src/registry.xml index 285a2402b8..6d70fb3475 100644 --- a/lib/erl_interface/doc/src/registry.xml +++ b/lib/erl_interface/doc/src/registry.xml @@ -11,7 +11,7 @@ Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at - + http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software @@ -19,7 +19,7 @@ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. - + </legalnotice> <title>registry</title> @@ -28,457 +28,585 @@ <docno></docno> <approved>Gordon Beaton</approved> <checked>Gordon Beaton</checked> - <date>980707</date> + <date>1998-07-07</date> <rev>A</rev> - <file>registry.sgml</file> + <file>registry.xml</file> </header> <lib>registry</lib> - <libsummary>Store and backup key-value pairs</libsummary> + <libsummary>Store and back up 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> + <seealso marker="mnesia:mnesia">Mnesia</seealso> + in an atomic manner, and later restoring the contents of a + registry from <c>Mnesia</c>.</p> </description> + <funcs> <func> - <name><ret>ei_reg *</ret><nametext>ei_reg_open(size)</nametext></name> - <fsummary>Create and open a registry</fsummary> + <name><ret>int</ret><nametext>ei_reg_close(reg)</nametext></name> + <fsummary>Close a registry.</fsummary> <type> - <v>int size;</v> + <v>ei_reg *reg;</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> + <p>A registry that has previously been created with + <c>ei_reg_open()</c> is closed, and all the objects it + contains are freed.</p> + <p><c>reg</c> is the registry to close.</p> + <p>Returns <c>0</c>.</p> </desc> </func> + <func> - <name><ret>int</ret><nametext>ei_reg_resize(reg,newsize)</nametext></name> - <fsummary>Resize a registry</fsummary> + <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>int newsize;</v> + <v>const char *key;</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> + <p>Deletes an object from the registry. The object is not + removed from the registry, it is only marked for later + removal so that on later backups to <c>Mnesia</c>, the + corresponding object can be removed from the <c>Mnesia</c> table as + well. If another object is later created with the same key, the + object will be reused. </p> + <p>The object is removed from the registry after a call to + <c>ei_reg_dump()</c> or <c>ei_reg_purge()</c>. + </p> + <list type="bulleted"> + <item><c>reg</c> is the registry containing + <c>key</c>.</item> + <item><c>key</c> is the object to remove.</item> + </list> + <p>Returns <c>0</c> on success, otherwise <c>-1</c>.</p> </desc> </func> + <func> - <name><ret>int</ret><nametext>ei_reg_close(reg)</nametext></name> - <fsummary>Close a registry </fsummary> + <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>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> + <p>Dumps the contents of a registry to a <c>Mnesia</c> table in an + atomic manner, that is, either all data or no data is updated. + If any errors are encountered while backing up + the data, the entire operation is aborted.</p> + <list type="bulleted"> + <item><c>fd</c> is an open connection to Erlang. + <c>Mnesia</c> 3.0 or later must be running on the Erlang node. + </item> + <item><c>reg</c> is the registry to back up.</item> + <item><c>mntab</c> is the name of the <c>Mnesia</c> table + where the backed up data is to be placed. If the table does not + exist, it is created automatically using configurable defaults. + For information about configuring this behavior, see + <seealso marker="mnesia:mnesia"><c>Mnesia</c></seealso>.</item> + </list> + <p>If <c>flags</c> is <c>0</c>, the backup includes only + those objects that have been created, modified, or deleted since the + last backup or restore (that is, 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 <c>EI_FORCE</c> causes a full + backup to be done, and <c>EI_NOPURGE</c> causes the deleted objects + to be left in the registry afterwards. These can be bitwise OR'ed + together if both behaviors are desired. If <c>EI_NOPURGE</c> was + specified, <c>ei_reg_purge()</c> can be used to + explicitly remove the deleted items from the registry later.</p> + <p>Returns <c>0</c> on success, otherwise <c>-1</c>.</p> </desc> </func> + <func> - <name><ret>int</ret><nametext>ei_reg_setival(reg,key,i)</nametext></name> - <fsummary>Assign an integer object</fsummary> + <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> - <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> + <p>Gets the value associated with <c>key</c> in the + registry. The value must be a floating point type.</p> + <list type="bulleted"> + <item><c>reg</c> is the registry where the object will be + looked up.</item> + <item><c>key</c> is the name of the object to look up. + </item> + </list> + <p>On success, the function returns the value associated with + <c>key</c>. + If the object is not found or if it is not a floating point + object, <c>-1.0</c> is returned. To avoid problems with in-band error + reporting (that is, if you cannot distinguish between <c>-1.0</c> and + a valid result), use the more general function + <c>ei_reg_getval()</c> instead.</p> </desc> </func> + <func> - <name><ret>int</ret><nametext>ei_reg_setfval(reg,key,f)</nametext></name> - <fsummary>Assign a floating point object</fsummary> + <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> - <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> + <p>Gets the value associated with <c>key</c> in the + registry. The value must be an integer.</p> + <list type="bulleted"> + <item><c>reg</c> is the registry where the object will be + looked up.</item> + <item><c>key</c> is the name of the object to look up. + </item> + </list> + <p>On success, the function returns the value associated with + <c>key</c>. + If the object is not found or if it is not an integer + object, <c>-1</c> is returned. To avoid problems with in-band error + reporting (that is, if you cannot distinguish between <c>-1</c> and a + valid result), use the more general function + <c>ei_reg_getval()</c> instead.</p> </desc> </func> + <func> - <name><ret>int</ret><nametext>ei_reg_setsval(reg,key,s)</nametext></name> - <fsummary>Assign a string object</fsummary> + <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>const char *s;</v> + <v>int size;</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> + <p>Gets the value associated with <c>key</c> in the + registry. The value must be a binary (pointer) type.</p> + <list type="bulleted"> + <item><c>reg</c> is the registry where the object will be + looked up.</item> + <item><c>key</c> is the name of the object to look up. + </item> + <item><c>size</c> is initialized to contain the length in + bytes of the object, if it is found.</item> + </list> + <p>On success, the function returns the value associated with + <c>key</c> and indicates its length in + <c>size</c>. + If the object is not found or if it is not a binary object, + <c>NULL</c> is returned. To avoid problems with in-band error + reporting (that is, if you cannot distinguish between <c>NULL</c> and + a valid result), use the more general function + <c>ei_reg_getval()</c> instead.</p> </desc> </func> + <func> - <name><ret>int</ret><nametext>ei_reg_setpval(reg,key,p,size)</nametext></name> - <fsummary>Assign a binary object</fsummary> + <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> - <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> + <p>Gets the value associated with <c>key</c> in the + registry. The value must be a string.</p> + <list type="bulleted"> + <item><c>reg</c> is the registry where the object will be + looked up.</item> + <item><c>key</c> is the name of the object to look up. + </item> + </list> + <p>On success, the function returns the value associated with + <c>key</c>. If the object is not found or if it is not a + string, <c>NULL</c> is returned. To avoid problems with in-band error + reporting (that is, if you cannot distinguish between <c>NULL</c> and + a valid result), use the more general function + <c>ei_reg_getval()</c> instead.</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> + <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>v (see below)</v> + <v>void *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> + <p>A general function for retrieving any kind of + object from the registry.</p> + <list type="bulleted"> + <item> + <p><c>reg</c> is the registry where the object will be + looked up.</p> + </item> + <item> + <p><c>key</c> is the name of the object to look up.</p> + </item> + <item> + <p><c>flags</c> indicates the type of object that you + are looking for. If <c>flags</c> is <c>0</c>, any + kind of object is returned. + If <c>flags</c> is <c>EI_INT</c>, <c>EI_FLT</c>, + <c>EI_STR</c>, or <c>EI_BIN</c>, then only values of + that kind are returned.</p> + <p>The buffer pointed to by <c>v</c> + must be large enough to hold the return data, that is, it must be + a pointer to one of <c>int</c>, + <c>double</c>, <c>char*</c>, or + <c>void*</c>, respectively.</p> + <p>If <c>flags</c> is <c>EI_BIN</c>, a fifth argument + <c>int *size</c> is required, so that the size of the + object can be returned.</p> + </item> + </list> + <p>On success, <c>v</c> (and <c>size</c> if the + object is binary) is initialized with the value associated + with <c>key</c>, and the function returns <c>EI_INT</c>, + <c>EI_FLT</c>, <c>EI_STR</c>, or <c>EI_BIN</c>, indicating the type + of object. On failure, <c>-1</c> is returned and the + arguments are not updated.</p> </desc> </func> + <func> - <name><ret>int</ret><nametext>ei_reg_getival(reg,key)</nametext></name> - <fsummary>Get an integer object</fsummary> + <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>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> + <p>Marks a registry object as dirty. This ensures that + it is included in the next backup to <c>Mnesia</c>. Normally this + operation is not necessary, as 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 is + invisible to the registry and the object is assumed to be + unmodified. This function allows you to make such modifications + and then let the registry know about them.</p> + <list type="bulleted"> + <item><c>reg</c> is the registry containing the object. + </item> + <item><c>key</c> is the name of the object to mark. + </item> + </list> + <p>Returns <c>0</c> on success, otherwise <c>-1</c>.</p> </desc> </func> + <func> - <name><ret>double</ret><nametext>ei_reg_getfval(reg,key)</nametext></name> - <fsummary>Get a floating point object</fsummary> + <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>Opens (creates) a registry, which initially is empty. To + close the registry later, use <c>ei_reg_close()</c>.</p> + <p><c>size</c> is the approximate number of objects you + intend to store in the registry. As the registry uses a hash table + with collision chaining, no absolute upper limit exists 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. To change the size later, use + <c>ei_reg_resize()</c>. Notice that the number + you provide is increased to the nearest larger prime number.</p> + <p>Returns an empty registry on success, otherwise <c>NULL</c>.</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> - <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> + <p>Removes all objects marked for deletion. When objects + are deleted with <c>ei_reg_delete()</c> they are not + removed from the registry, only marked for later removal. + On a later backup to <c>Mnesia</c>, the + objects can also be removed from the <c>Mnesia</c> table. If you are + not backing up to <c>Mnesia</c>, you may wish to remove the objects + manually with this function.</p> + <p><c>reg</c> is a registry containing objects marked for + deletion.</p> + <p>Returns <c>0</c> on success, otherwise <c>-1</c>.</p> </desc> </func> + <func> - <name><ret>const char *</ret><nametext>ei_reg_getsval(reg,key)</nametext></name> - <fsummary>Get a string object</fsummary> + <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>Changes the size of a registry.</p> + <p><c>newsize</c> is the new size to make the registry. The + number is increased to the nearest larger prime number.</p> + <p>On success, the registry is resized, all contents + rehashed, and <c>0</c> is returned. On failure, the + registry is left unchanged and <c>-1</c> is returned.</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 <c>Mnesia</c> table are read into the registry.</p> + <list type="bulleted"> + <item><c>fd</c> is an open connection to Erlang. + <c>Mnesia</c> 3.0 or later must be running on the Erlang node. + </item> + <item><c>reg</c> is the registry where the data is to be + placed.</item> + <item><c>mntab</c> is the name of the <c>Mnesia</c> table + to read data from.</item> + </list> + <p>Notice that only tables of a certain format can be + restored, that is, those that have been created and backed up to + with <c>ei_reg_dump()</c>. If the registry was not empty + before the operation, 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 + are overwritten with the new values. If the registry + contains objects that were not in the table, they are + unchanged by this operation.</p> + <p>After the restore operation, the entire contents of the + registry is marked as unmodified. Notice that this includes any + objects that were modified before the restore and not + overwritten by the restore.</p> + <p>Returns <c>0</c> on success, otherwise <c>-1</c>.</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>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> + <p>Creates a key-value pair with the specified <c>key</c> + and floating point value <c>f</c>. If an object already + exists with the same <c>key</c>, the new value replaces + the old one. If the previous value was a binary or string, it is + freed with <c>free()</c>.</p> + <list type="bulleted"> + <item><c>reg</c> is the registry where the object is to be + placed.</item> + <item><c>key</c> is the object name.</item> + <item><c>f</c> is the floating point value to assign. + </item> + </list> + <p>Returns <c>0</c> on success, otherwise <c>-1</c>.</p> </desc> </func> + <func> - <name><ret>const void *</ret><nametext>ei_reg_getpval(reg,key,size)</nametext></name> - <fsummary>Get a binary object</fsummary> + <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 size;</v> + <v>int i;</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> + <p>Creates a key-value pair with the specified <c>key</c> + and integer value <c>i</c>. If an object already exists + with the same <c>key</c>, the new value replaces the old + one. If the previous value was a binary or string, it is freed with + <c>free()</c>.</p> + <list type="bulleted"> + <item><c>reg</c> is the registry where the object is to be + placed.</item> + <item><c>key</c> is the object name.</item> + <item><c>i</c> is the integer value to assign.</item> + </list> + <p>Returns <c>0</c> on success, otherwise <c>-1</c>.</p> </desc> </func> + <func> - <name><ret>int</ret><nametext>ei_reg_getval(reg,key,flags,v,...)</nametext></name> - <fsummary>Get any object</fsummary> + <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>int flags;</v> - <v>void *v (see below)</v> + <v>const void *p;</v> + <v>int size;</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> + <p>Creates a key-value pair with the specified <c>key</c> + whose "value" is the binary object pointed to by <c>p</c>. + If an object already exists with the same <c>key</c>, + the new value replaces the old one. If the previous value was a + binary or string, it is freed with <c>free()</c>.</p> + <list type="bulleted"> + <item><c>reg</c> is the registry where the object is to be + placed.</item> + <item><c>key</c> is the object name.</item> + <item><c>p</c> is a pointer to the binary object. The + object itself must have been created through a single call to + <c>malloc()</c> or a similar function, so that the + registry can later delete it if necessary by calling + <c>free()</c>.</item> + <item><c>size</c> is the length in bytes of the binary + object.</item> + </list> + <p>Returns <c>0</c> on success, otherwise <c>-1</c>.</p> </desc> </func> + <func> - <name><ret>int</ret><nametext>ei_reg_markdirty(reg,key)</nametext></name> - <fsummary>Mark an object as dirty </fsummary> + <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>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> + <p>Creates a key-value pair with the specified <c>key</c> + whose "value" is the specified string <c>s</c>. If an + object already exists with the same <c>key</c>, the new + value replaces the old one. If the previous value was a binary or + string, it is freed with <c>free()</c>.</p> + <list type="bulleted"> + <item><c>reg</c> is the registry where the object is to be + placed.</item> + <item><c>key</c> is the object name.</item> + <item><c>s</c> is the string to assign. The string itself + must have been created through a single call to + <c>malloc()</c> or similar a function, + so that the registry can later delete it if + necessary by calling <c>free()</c>.</item> + </list> + <p>Returns <c>0</c> on success, otherwise <c>-1</c>.</p> </desc> </func> + <func> - <name><ret>int</ret><nametext>ei_reg_delete(reg,key)</nametext></name> - <fsummary>Delete an object from the registry</fsummary> + <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>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> + <p>Creates a key-value pair with the specified <c>key</c> + whose value is specified by <c>v</c>. If an object already + exists with the same <c>key</c>, the new value replaces + the old one. If the previous value was a binary or string, it is freed + with <c>free()</c>.</p> + <list type="bulleted"> + <item> + <p><c>reg</c> is the registry where the object is to be + placed.</p> + </item> + <item> + <p><c>key</c> is the object name.</p> + </item> + <item> + <p><c>flags</c> indicates the type of the object + specified by <c>v</c>. Flags must be one of + <c>EI_INT</c>, <c>EI_FLT</c>, <c>EI_STR</c>, and <c>EI_BIN</c>, + indicating whether + <c>v</c> is <c>int</c>, + <c>double</c>, <c>char*</c>, or + <c>void*</c>.</p> + <p>If <c>flags</c> is <c>EI_BIN</c>, a fifth argument + <c>size</c> is required, indicating the size + in bytes of the object pointed to by <c>v</c>.</p> + </item> + </list> + <p>If you wish to store an arbitrary pointer in the registry, + specify a <c>size</c> of <c>0</c>. In this case, the + object itself is not transferred by an + <c>ei_reg_dump()</c> operation, only the pointer + value.</p> + <p>Returns <c>0</c> on success, otherwise <c>-1</c>.</p> </desc> </func> + <func> <name><ret>int</ret><nametext>ei_reg_stat(reg,key,obuf)</nametext></name> - <fsummary>Get object information</fsummary> + <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> + <p>Returns information about an object.</p> + <list type="bulleted"> + <item><c>reg</c> is the registry containing the object. + </item> + <item><c>key</c> is the object name.</item> + <item><c>obuf</c> is a pointer to an + <c>ei_reg_stat</c> structure, defined as follows:</item> + </list> <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> + <p>In <c>attr</c> the attributes of the object are stored + as the logical <em>OR</em> of its type (one of <c>EI_INT</c>, + <c>EI_FLT</c>, <c>EI_BIN</c>, and <c>EI_STR</c>), + whether it is marked for deletion (<c>EI_DELET</c>), and whether it + has been modified since the last backup to <c>Mnesia</c> + (<c>EI_DIRTY</c>).</p> + <p>Field <c>size</c> indicates the size in bytes required + to store <c>EI_STR</c> (including the terminating <c>0</c>) and + <c>EI_BIN</c> objects, or <c>0</c> for <c>EI_INT</c> and + <c>EI_FLT</c>.</p> + <p>Returns <c>0</c> and initializes <c>obuf</c> on success, + otherwise <c>-1</c>.</p> </desc> </func> + <func> <name><ret>int</ret><nametext>ei_reg_tabstat(reg,obuf)</nametext></name> - <fsummary>Get registry information</fsummary> + <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 + <p>Returns 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> + registry is suitable for the amount of data it contains.</p> + <list type="bulleted"> + <item><c>reg</c> is the registry to return information + about.</item> + <item><c>obuf</c> is a pointer to an + <c>ei_reg_tabstat</c> structure, defined as follows: + </item> + </list> <code type="none"><![CDATA[ struct ei_reg_tabstat { int size; @@ -487,126 +615,23 @@ struct ei_reg_tabstat { int collisions; }; ]]></code> - <p>The <c><![CDATA[size]]></c> field indicates the number of hash positions + <p>Field <c>size</c> 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> + prime number.</p> + <list type="bulleted"> + <item><c>nelem</c> indicates the number of elements stored + in the registry. It includes objects that are deleted but not + purged.</item> + <item><c>npos</c> indicates the number of unique positions + that are occupied in the registry.</item> + <item><c>collisions</c> indicates how many elements are + sharing positions in the registry.</item> + </list> + <p>On success, <c>0</c> is returned and + <c>obuf</c> is initialized to contain table statistics, + otherwise <c>-1</c> is returned.</p> </desc> </func> </funcs> </cref> - |