1
<?xml version="1.0" encoding="latin1" ?>
2
<!DOCTYPE chapter SYSTEM "chapter.dtd">
9
<holder>Ericsson AB, All Rights Reserved</holder>
12
The contents of this file are subject to the Erlang Public License,
13
Version 1.1, (the "License"); you may not use this file except in
14
compliance with the License. You should have received a copy of the
15
Erlang Public License along with this software. If not, it can be
16
retrieved online at http://www.erlang.org/.
18
Software distributed under the License is distributed on an "AS IS"
19
basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
20
the License for the specific language governing rights and limitations
23
The Initial Developer of the Original Code is Ericsson AB.
26
<title>The Erl_Interface Library</title>
27
<prepared>Torbjörn Törnkvist</prepared>
28
<responsible>Torbjörn Törnkvist</responsible>
30
<approved>Bjarne Däcker</approved>
31
<checked>K.Lundin</checked>
34
<file>erl_interface.sgml</file>
36
<p>The Erl_Interface library contains functions. which help you
37
integrate programs written in C and Erlang. The functions in
38
Erl_Interface support the following:</p>
39
<list type="bulleted">
40
<item>manipulation of data represented as Erlang data types</item>
41
<item>conversion of data between C and Erlang formats</item>
42
<item>encoding and decoding of Erlang data types for transmission or storage</item>
43
<item>communication between C nodes and Erlang processes</item>
44
<item>backup and restore of C node state to and from Mnesia</item>
46
<p>In the following sections, these topics are described:</p>
47
<list type="bulleted">
48
<item>compiling your code for use with Erl_Interface</item>
49
<item>initializing Erl_Interface</item>
50
<item>encoding, decoding, and sending Erlang terms</item>
51
<item>building terms and patterns</item>
52
<item>pattern matching</item>
53
<item>connecting to a distributed Erlang node</item>
54
<item>using EPMD</item>
55
<item>sending and receiving Erlang messages</item>
56
<item>remote procedure calls</item>
57
<item>global names</item>
58
<item>the registry</item>
62
<title>Compiling and Linking Your Code</title>
63
<p>In order to use any of the Erl_Interface functions, include the
64
following lines in your code:</p>
65
<code type="none"><![CDATA[
66
#include "erl_interface.h"
67
#include "ei.h" ]]></code>
68
<p>Determine where the top directory of your OTP installation is. You
69
can find this out by starting Erlang and entering the following
70
command at the Eshell prompt:</p>
71
<code type="none"><![CDATA[
72
Eshell V4.7.4 (abort with ^G)
74
/usr/local/otp ]]></code>
75
<p>To compile your code, make sure that your C compiler knows where
76
to find <c><![CDATA[erl_interface.h]]></c> by specifying an appropriate <c><![CDATA[-I]]></c>
77
argument on the command line, or by adding it to the <c><![CDATA[CFLAGS]]></c>
78
definition in your <c><![CDATA[Makefile]]></c>. The correct value for this path is
79
<c><![CDATA[$OTPROOT/lib/erl_interface]]></c><em>Vsn</em><c><![CDATA[/include]]></c>, where <c><![CDATA[$OTPROOT]]></c> is the path
80
reported by <c><![CDATA[code:root_dir/0]]></c> in the above example, and <em>Vsn</em> is
81
the version of the Erl_interface application, for example
82
<c><![CDATA[erl_interface-3.2.3]]></c></p>
83
<code type="none"><![CDATA[
84
$ cc -c -I/usr/local/otp/lib/erl_interface-3.2.3/include myprog.c ]]></code>
85
<p>When linking, you will need to specify the path to
86
<c><![CDATA[liberl_interface.a]]></c> and <c><![CDATA[libei.a]]></c> with
87
<c><![CDATA[-L$OTPROOT/lib/erl_interface-3.2.3/lib]]></c>, and you will need to specify the
88
name of the libraries with <c><![CDATA[-lerl_interface -lei]]></c>. You can do
89
this on the command line or by adding the flags to the <c><![CDATA[LDFLAGS]]></c>
90
definition in your <c><![CDATA[Makefile]]></c>.</p>
91
<code type="none"><![CDATA[
92
$ ld -L/usr/local/otp/lib/erl_interface-3.2.3/
93
lib myprog.o -lerl_interface -lei -o myprog ]]></code>
94
<p>Also, on some systems it may be necessary to link with some
95
additional libraries (e.g. <c><![CDATA[libnsl.a]]></c> and <c><![CDATA[libsocket.a]]></c> on
96
Solaris, or <c><![CDATA[wsock32.lib]]></c> on Windows) in order to use the
97
communication facilities of Erl_Interface.</p>
98
<p>If you are using Erl_Interface functions in a threaded
99
application based on POSIX threads or Solaris threads, then
100
Erl_Interface needs access to some of the synchronization
101
facilities in your threads package, and you will need to specify
102
additional compiler flags in order to indicate which of the packages
103
you are using. Define <c><![CDATA[_REENTRANT]]></c> and either <c><![CDATA[STHREADS]]></c> or
104
<c><![CDATA[PTHREADS]]></c>. The default is to use POSIX threads if
105
<c><![CDATA[_REENTRANT]]></c> is specified.</p>
106
<p>Note that both single threaded and default versions of the Erl_interface
107
and Ei libraries are provided. (The single threaded versions are named
108
<c><![CDATA[liberl_interface_st]]></c> and <c><![CDATA[libei_st]]></c>). Whether the default
109
versions of the libraries have support for threads or not is determined by if
110
the platform in question has support for POSIX or Solaris threads. To check this,
111
have a look in the <c><![CDATA[eidefs.mk]]></c> file in the erl_interface src directory.</p>
115
<title>Initializing the erl_interface Library</title>
116
<p>Before calling any of the other Erl_Interface functions, you
117
must call <c><![CDATA[erl_init()]]></c> exactly once to initialize the library.
118
<c><![CDATA[erl_init()]]></c> takes two arguments, however the arguments are no
119
longer used by Erl_Interface, and should therefore be specified
120
as <c><![CDATA[erl_init(NULL,0)]]></c>.</p>
124
<title>Encoding, Decoding and Sending Erlang Terms</title>
125
<p>Data sent between distributed Erlang nodes is encoded in the
126
Erlang external format. Consequently, you have to encode and decode
127
Erlang terms into byte streams if you want to use the distribution
128
protocol to communicate between a C program and Erlang. </p>
129
<p>The Erl_Interface library supports this activity. It has a
130
number of C functions which create and manipulate Erlang data
131
structures. The library also contains an encode and a decode function.
132
The example below shows how to create and encode an Erlang tuple
133
<c><![CDATA[{tobbe,3928}]]></c>:</p>
134
<code type="none"><![CDATA[
136
ETERM *arr[2], *tuple;
140
arr[0] = erl_mk_atom("tobbe");
141
arr[1] = erl_mk_integer(3928);
142
tuple = erl_mk_tuple(arr, 2);
143
i = erl_encode(tuple, buf); ]]></code>
144
<p>Alternatively, you can use <c><![CDATA[erl_send()]]></c> and
145
<c><![CDATA[erl_receive_msg]]></c>, which handle the encoding and decoding of
146
messages transparently.</p>
147
<p>Refer to the Reference Manual for a complete description of the
148
following modules:</p>
149
<list type="bulleted">
150
<item>the <c><![CDATA[erl_eterm]]></c> module for creating Erlang terms</item>
151
<item>the <c><![CDATA[erl_marshal]]></c> module for encoding and decoding routines.</item>
156
<title>Building Terms and Patterns</title>
157
<p>The previous example can be simplified by using
158
<c><![CDATA[erl_format()]]></c> to create an Erlang term.</p>
159
<code type="none"><![CDATA[
162
ep = erl_format("{~a,~i}", "tobbe", 3928); ]]></code>
163
<p>Refer to the Reference Manual, the <c><![CDATA[erl_format]]></c> module, for a
164
full description of the different format directives. The following
165
example is more complex:</p>
166
<code type="none"><![CDATA[
169
ep = erl_format("[{name,~a},{age,~i},{data,~w}]",
172
erl_format("[{adr,~s,~i}]", "E-street", 42));
173
erl_free_compound(ep); ]]></code>
174
<p>As in previous examples, it is your responsibility to free the
175
memory allocated for Erlang terms. In this example,
176
<c><![CDATA[erl_free_compound()]]></c> ensures that the complete term pointed to
177
by <c><![CDATA[ep]]></c> is released. This is necessary, because the pointer from
178
the second call to <c><![CDATA[erl_format()]]></c> is lost. </p>
180
example shows a slightly different solution:</p>
181
<code type="none"><![CDATA[
184
ep2 = erl_format("[{adr,~s,~i}]","E-street",42);
185
ep = erl_format("[{name,~a},{age,~i},{data,~w}]",
188
erl_free_term(ep2); ]]></code>
189
<p>In this case, you free the two terms independently. The order in
190
which you free the terms <c><![CDATA[ep]]></c> and <c><![CDATA[ep2]]></c> is not important,
191
because the Erl_Interface library uses reference counting to
192
determine when it is safe to actually remove objects. </p>
193
<p>If you are not sure whether you have freed the terms properly, you
194
can use the following function to see the status of the fixed term
196
<code type="none"><![CDATA[
197
long allocated, freed;
199
erl_eterm_statistics(&allocated,&freed);
200
printf("currently allocated blocks: %ld\
202
printf("length of freelist: %ld\
205
/* really free the freelist */
208
<p>Refer to the Reference Manual, the <c><![CDATA[erl_malloc]]></c> module for more
213
<title>Pattern Matching</title>
214
<p>An Erlang pattern is a term that may contain unbound variables or
215
<c><![CDATA["do not care"]]></c> symbols. Such a pattern can be matched against a
216
term and, if the match is successful, any unbound variables in the
217
pattern will be bound as a side effect. The content of a bound
218
variable can then be retrieved.</p>
219
<code type="none"><![CDATA[
222
pattern = erl_format("{madonna,Age,_}"); ]]></code>
223
<p><c><![CDATA[erl_match()]]></c> is used to perform pattern matching. It takes a
224
pattern and a term and tries to match them. As a side effect any unbound
225
variables in the pattern will be bound. In the following example, we
226
create a pattern with a variable <em>Age</em> which appears at two
227
positions in the tuple. The pattern match is performed as follows:</p>
228
<list type="ordered">
229
<item><c><![CDATA[erl_match()]]></c> will bind the contents of
230
<em>Age</em> to <em>21</em> the first time it reaches the variable</item>
231
<item>the second occurrence of <em>Age</em> will cause a test for
232
equality between the terms since <em>Age</em> is already bound to
233
<em>21</em>. Since <em>Age</em> is bound to 21, the equality test will
234
succeed and the match continues until the end of the pattern.</item>
235
<item>if the end of the pattern is reached, the match succeeds and you
236
can retrieve the contents of the variable</item>
238
<code type="none"><![CDATA[
239
ETERM *pattern,*term;
240
pattern = erl_format("{madonna,Age,Age}");
241
term = erl_format("{madonna,21,21}");
242
if (erl_match(pattern, term)) {
243
fprintf(stderr, "Yes, they matched: Age = ");
244
ep = erl_var_content(pattern, "Age");
245
erl_print_term(stderr, ep);
250
erl_free_term(pattern);
251
erl_free_term(term); ]]></code>
252
<p>Refer to the Reference Manual, the <c><![CDATA[erl_match()]]></c> function for
253
more information.</p>
257
<title>Connecting to a Distributed Erlang Node</title>
258
<p>In order to connect to a distributed Erlang node you need to first
259
initialize the connection routine with <c><![CDATA[erl_connect_init()]]></c>,
260
which stores information such as the host name, node name, and IP
261
address for later use:</p>
262
<code type="none"><![CDATA[
263
int identification_number = 99;
265
char *cookie="a secret cookie string"; /* An example */
266
erl_connect_init(identification_number, cookie, creation); ]]></code>
267
<p>Refer to the Reference Manual, the <c><![CDATA[erl_connect]]></c> module for more information.</p>
268
<p>After initialization, you set up the connection to the Erlang node.
269
Use <c><![CDATA[erl_connect()]]></c> to specify the Erlang node you want to
270
connect to. The following example sets up the connection and should
271
result in a valid socket file descriptor:</p>
272
<code type="none"><![CDATA[
274
char *nodename="xyz@chivas.du.etx.ericsson.se"; /* An example */
275
if ((sockfd = erl_connect(nodename)) < 0)
276
erl_err_quit("ERROR: erl_connect failed"); ]]></code>
277
<p><c><![CDATA[erl_err_quit()]]></c> prints the specified string and terminates
278
the program. Refer to the Reference Manual, the <c><![CDATA[erl_error()]]></c>
279
function for more information.</p>
283
<title>Using EPMD</title>
284
<p><c><![CDATA[Epmd]]></c> is the Erlang Port Mapper Daemon. Distributed Erlang nodes
285
register with <c><![CDATA[epmd]]></c> on the localhost to indicate to other nodes that
286
they exist and can accept connections. <c><![CDATA[Epmd]]></c> maintains a register of
287
node and port number information, and when a node wishes to connect to
288
another node, it first contacts <c><![CDATA[epmd]]></c> in order to find out the correct
289
port number to connect to.</p>
290
<p>When you use <c><![CDATA[erl_connect()]]></c> to connect to an Erlang node, a
291
connection is first made to <c><![CDATA[epmd]]></c> and, if the node is known, a
292
connection is then made to the Erlang node.</p>
293
<p>C nodes can also register themselves with <c><![CDATA[epmd]]></c> if they want other
294
nodes in the system to be able to find and connect to them.</p>
295
<p>Before registering with <c><![CDATA[epmd]]></c>, you need to first create a listen socket
296
and bind it to a port. Then:</p>
297
<code type="none"><![CDATA[
300
pub = erl_publish(port); ]]></code>
301
<p><c><![CDATA[pub]]></c> is a file descriptor now connected to <c><![CDATA[epmd]]></c>. <c><![CDATA[Epmd]]></c>
302
monitors the other end of the connection, and if it detects that the
303
connection has been closed, the node will be unregistered. So, if you
304
explicitly close the descriptor or if your node fails, it will be
305
unregistered from <c><![CDATA[epmd]]></c>.</p>
306
<p>Be aware that on some systems (such as VxWorks), a failed node will
307
not be detected by this mechanism since the operating system does not
308
automatically close descriptors that were left open when the node
309
failed. If a node has failed in this way, <c><![CDATA[epmd]]></c> will prevent you from
310
registering a new node with the old name, since it thinks that the old
311
name is still in use. In this case, you must unregister the name
313
<code type="none"><![CDATA[
314
erl_unpublish(node); ]]></code>
315
<p>This will cause <c><![CDATA[epmd]]></c> to close the connection from the far end. Note
316
that if the name was in fact still in use by a node, the results of
317
this operation are unpredictable. Also, doing this does not cause the
318
local end of the connection to close, so resources may be consumed.</p>
322
<title>Sending and Receiving Erlang Messages</title>
323
<p>Use one of the following two functions to send messages:</p>
324
<list type="bulleted">
325
<item><c><![CDATA[erl_send()]]></c></item>
326
<item><c><![CDATA[erl_reg_send()]]></c></item>
328
<p>As in Erlang, it is possible to send messages to a
329
<em>Pid</em> or to a registered name. It is easier to send a
330
message to a registered name because it avoids the problem of finding
331
a suitable <em>Pid</em>.</p>
332
<p>Use one of the following two functions to receive messages:</p>
333
<list type="bulleted">
334
<item><c><![CDATA[erl_receive()]]></c></item>
335
<item><c><![CDATA[erl_receive_msg()]]></c></item>
337
<p><c><![CDATA[erl_receive()]]></c> receives the message into a buffer, while
338
<c><![CDATA[erl_receive_msg()]]></c> decodes the message into an Erlang term. </p>
341
<title>Example of Sending Messages</title>
342
<p>In the following example, <c><![CDATA[{Pid, hello_world}]]></c> is
343
sent to a registered process <c><![CDATA[my_server]]></c>. The message is encoded
344
by <c><![CDATA[erl_send()]]></c>:</p>
345
<code type="none"><![CDATA[
346
extern const char *erl_thisnodename(void);
347
extern short erl_thiscreation(void);
348
#define SELF(fd) erl_mk_pid(erl_thisnodename(),fd,0,erl_thiscreation())
349
ETERM *arr[2], *emsg;
350
int sockfd, creation=1;
352
arr[0] = SELF(sockfd);
353
arr[1] = erl_mk_atom("Hello world");
354
emsg = erl_mk_tuple(arr, 2);
356
erl_reg_send(sockfd, "my_server", emsg);
357
erl_free_term(emsg); ]]></code>
358
<p>The first element of the tuple that is sent is your own
359
<em>Pid</em>. This enables <c><![CDATA[my_server]]></c> to reply. Refer to the
360
Reference Manual, the <c><![CDATA[erl_connect]]></c> module for more information
361
about send primitives.</p>
365
<title>Example of Receiving Messages</title>
366
<p>In this example <c><![CDATA[{Pid, Something}]]></c> is received. The
367
received Pid is then used to return <c><![CDATA[{goodbye,Pid}]]></c></p>
368
<code type="none"><![CDATA[
369
ETERM *arr[2], *answer;
374
if ((rc = erl_receive_msg(sockfd , buf, BUFSIZE, &emsg)) == ERL_MSG) {
375
arr[0] = erl_mk_atom("goodbye");
376
arr[1] = erl_element(1, emsg.msg);
377
answer = erl_mk_tuple(arr, 2);
378
erl_send(sockfd, arr[1], answer);
379
erl_free_term(answer);
380
erl_free_term(emsg.msg);
381
erl_free_term(emsg.to);
384
<p>In order to provide robustness, a distributed Erlang node
385
occasionally polls all its connected neighbours in an attempt to
386
detect failed nodes or communication links. A node which receives such
387
a message is expected to respond immediately with an <c><![CDATA[ERL_TICK]]></c> message.
388
This is done automatically by <c><![CDATA[erl_receive()]]></c>, however when this
389
has occurred <c><![CDATA[erl_receive]]></c> returns <c><![CDATA[ERL_TICK]]></c> to the caller
390
without storing a message into the <c><![CDATA[ErlMessage]]></c> structure.</p>
391
<p>When a message has been received, it is the caller's responsibility
392
to free the received message <c><![CDATA[emsg.msg]]></c> as well as <c><![CDATA[emsg.to]]></c>
393
or <c><![CDATA[emsg.from]]></c>, depending on the type of message received.</p>
394
<p>Refer to the Reference Manual for additional information about the
395
following modules:</p>
396
<list type="bulleted">
397
<item><c><![CDATA[erl_connect]]></c></item>
398
<item><c><![CDATA[erl_eterm]]></c>.</item>
404
<title>Remote Procedure Calls</title>
405
<p>An Erlang node acting as a client to another Erlang node
406
typically sends a request and waits for a reply. Such a request is
407
included in a function call at a remote node and is called a remote
408
procedure call. The following example shows how the
409
Erl_Interface library supports remote procedure calls:</p>
410
<code type="none"><![CDATA[
412
char modname[]=THE_MODNAME;
414
ep = erl_format("[~a,[]]", modname);
415
if (!(reply = erl_rpc(fd, "c", "c", ep)))
416
erl_err_msg("<ERROR> when compiling file: %s.erl !\
419
ep = erl_format("{ok,_}");
420
if (!erl_match(ep, reply))
421
erl_err_msg("<ERROR> compiler errors !\
424
erl_free_term(reply); ]]></code>
425
<p><c><![CDATA[c:c/1]]></c> is called to compile the specified module on the
426
remote node. <c><![CDATA[erl_match()]]></c> checks that the compilation was
427
successful by testing for the expected <c><![CDATA[ok]]></c>.</p>
428
<p>Refer to the Reference Manual, the <c><![CDATA[erl_connect]]></c> module for
429
more information about <c><![CDATA[erl_rpc()]]></c>, and its companions
430
<c><![CDATA[erl_rpc_to()]]></c> and <c><![CDATA[erl_rpc_from()]]></c>.</p>
434
<title>Using Global Names</title>
435
<p>A C node has access to names registered through the Erlang Global
436
module. Names can be looked up, allowing the C node to send messages
437
to named Erlang services. C nodes can also register global names,
438
allowing them to provide named services to Erlang processes or other C
440
<p>Erl_Interface does not provide a native implementation of the global
441
service. Instead it uses the global services provided by a "nearby"
442
Erlang node. In order to use the services described in this section,
443
it is necessary to first open a connection to an Erlang node.</p>
444
<p>To see what names there are:</p>
445
<code type="none"><![CDATA[
450
names = erl_global_names(fd,&count);
453
for (i=0; i<count; i++)
457
free(names); ]]></code>
458
<p><c><![CDATA[erl_global_names()]]></c> allocates and returns a buffer containing
459
all the names known to global. <c><![CDATA[count]]></c> will be initialized to
460
indicate how many names are in the array. The array of strings in
461
names is terminated by a NULL pointer, so it is not necessary to use
462
<c><![CDATA[count]]></c> to determine when the last name is reached.</p>
463
<p>It is the caller's responsibility to free the array.
464
<c><![CDATA[erl_global_names()]]></c> allocates the array and all of the strings
465
using a single call to <c><![CDATA[malloc()]]></c>, so <c><![CDATA[free(names)]]></c> is all
466
that is necessary.</p>
467
<p>To look up one of the names:</p>
468
<code type="none"><![CDATA[
472
pid = erl_global_whereis(fd,"schedule",node); ]]></code>
473
<p>If <c><![CDATA["schedule"]]></c> is known to global, an Erlang pid is returned
474
that can be used to send messages to the schedule service.
475
Additionally, <c><![CDATA[node]]></c> will be initialized to contain the name of
476
the node where the service is registered, so that you can make a
477
connection to it by simply passing the variable to <c><![CDATA[erl_connect()]]></c>.</p>
478
<p>Before registering a name, you should already have registered your
479
port number with <c><![CDATA[epmd]]></c>. This is not strictly necessary, but if you
480
neglect to do so, then other nodes wishing to communicate with your
481
service will be unable to find or connect to your process.</p>
482
<p>Create a pid that Erlang processes can use to communicate with your
484
<code type="none"><![CDATA[
487
pid = erl_mk_pid(thisnode,14,0,0);
488
erl_global_register(fd,servicename,pid); ]]></code>
489
<p>After registering the name, you should use <c><![CDATA[erl_accept()]]></c> to wait for
490
incoming connections.</p>
491
<p>Do not forget to free <c><![CDATA[pid]]></c> later with <c><![CDATA[erl_free_term()]]></c>!</p>
492
<p>To unregister a name:</p>
493
<code type="none"><![CDATA[
494
erl_global_unregister(fd,servicename); ]]></code>
498
<title>The Registry</title>
499
<p>This section describes the use of the registry, a simple mechanism
500
for storing key-value pairs in a C-node, as well as backing them up or
501
restoring them from a Mnesia table on an Erlang node. More detailed
502
information about the individual API functions can be found in the
503
Reference Manual.</p>
504
<p>Keys are strings, i.e. 0-terminated arrays of characters, and values
505
are arbitrary objects. Although integers and floating point numbers
506
are treated specially by the registry, you can store strings or binary
507
objects of any type as pointers.</p>
508
<p>To start, you need to open a registry:</p>
509
<code type="none"><![CDATA[
512
reg = ei_reg_open(45); ]]></code>
513
<p>The number 45 in the example indicates the approximate number of
514
objects that you expect to store in the registry. Internally the
515
registry uses hash tables with collision chaining, so there is no
516
absolute upper limit on the number of objects that the registry can
517
contain, but if performance or memory usage are important, then you
518
should choose a number accordingly. The registry can be resized later.</p>
519
<p>You can open as many registries as you like (if memory permits).</p>
520
<p>Objects are stored and retrieved through set and get functions. In
521
the following examples you see how to store integers, floats, strings
522
and arbitrary binary objects:</p>
523
<code type="none"><![CDATA[
524
struct bonk *b = malloc(sizeof(*b));
525
char *name = malloc(7);
527
ei_reg_setival(reg,"age",29);
528
ei_reg_setfval(reg,"height",1.85);
530
strcpy(name,"Martin");
531
ei_reg_setsval(reg,"name",name);
535
ei_reg_setpval(reg,"jox",b,sizeof(*b)); ]]></code>
536
<p>If you attempt to store an object in the registry and there is an
537
existing object with the same key, the new value will replace the old
538
one. This is done regardless of whether the new object and the old one
539
have the same type, so you can, for example, replace a string with an
540
integer. If the existing value is a string or binary, it will be freed
541
before the new value is assigned.</p>
542
<p>Stored values are retrieved from the registry as follows:</p>
543
<code type="none"><![CDATA[
550
i = ei_reg_getival(reg,"age");
551
f = ei_reg_getfval(reg,"height");
552
s = ei_reg_getsval(reg,"name");
553
b = ei_reg_getpval(reg,"jox",&size); ]]></code>
554
<p>In all of the above examples, the object must exist and it must be of
555
the right type for the specified operation. If you do not know the
556
type of a given object, you can ask:</p>
557
<code type="none"><![CDATA[
558
struct ei_reg_stat buf;
560
ei_reg_stat(reg,"name",&buf); ]]></code>
561
<p>Buf will be initialized to contain object attributes.</p>
562
<p>Objects can be removed from the registry:</p>
563
<code type="none"><![CDATA[
564
ei_reg_delete(reg,"name"); ]]></code>
565
<p>When you are finished with a registry, close it to remove all the
566
objects and free the memory back to the system:</p>
567
<code type="none"><![CDATA[
568
ei_reg_close(reg); ]]></code>
571
<title>Backing Up the Registry to Mnesia</title>
572
<p>The contents of a registry can be backed up to Mnesia on a "nearby"
573
Erlang node. You need to provide an open connection to the Erlang node
574
(see <c><![CDATA[erl_connect()]]></c>). Also, Mnesia 3.0 or later must be running
575
on the Erlang node before the backup is initiated:</p>
576
<code type="none"><![CDATA[
577
ei_reg_dump(fd, reg, "mtab", dumpflags); ]]></code>
578
<p>The example above will backup the contents of the registry to the
579
specified Mnesia table <c><![CDATA["mtab"]]></c>. Once a registry has been backed
580
up to Mnesia in this manner, additional backups will only affect
581
objects that have been modified since the most recent backup, i.e.
582
objects that have been created, changed or deleted. The backup
583
operation is done as a single atomic transaction, so that the entire
584
backup will be performed or none of it will.</p>
585
<p>In the same manner, a registry can be restored from a Mnesia table:</p>
586
<code type="none"><![CDATA[
587
ei_reg_restore(fd, reg, "mtab"); ]]></code>
588
<p>This will read the entire contents of <c><![CDATA["mtab"]]></c> into the specified
589
registry. After the restore, all of the objects in the registry will
590
be marked as unmodified, so a subsequent backup will only affect
591
objects that you have modified since the restore.</p>
592
<p>Note that if you restore to a non-empty registry, objects in the
593
table will overwrite objects in the registry with the same keys. Also,
594
the <em>entire</em> contents of the registry is marked as unmodified
595
after the restore, including any modified obects that were not
596
overwritten by the restore operation. This may not be your intention.</p>
600
<title>Storing Strings and Binaries</title>
601
<p>When string or binary objects are stored in the registry it is
602
important that a number of simple guidelines are followed. </p>
603
<p>Most importantly, the object must have been created with a single call
604
to <c><![CDATA[malloc()]]></c> (or similar), so that it can later be removed by a
605
single call to <c><![CDATA[free()]]></c>. Objects will be freed by the registry
606
when it is closed, or when you assign a new value to an object that
607
previously contained a string or binary.</p>
608
<p>You should also be aware that if you store binary objects that are
609
context-dependent (e.g. containing pointers or open file descriptors),
610
they will lose their meaning if they are backed up to a Mnesia table
611
and subsequently restored in a different context.</p>
612
<p>When you retrieve a stored string or binary value from the registry,
613
the registry maintains a pointer to the object and you are passed a
614
copy of that pointer. You should never free an object retrieved in
615
this manner because when the registry later attempts to free it, a
616
runtime error will occur that will likely cause the C-node to crash.</p>
617
<p>You are free to modify the contents of an object retrieved this way.
618
However when you do so, the registry will not be aware of the changes
619
you make, possibily causing it to be missed the next time you make a
620
Mnesia backup of the registry contents. This can be avoided if you
621
mark the object as dirty after any such changes with
622
<c><![CDATA[ei_reg_markdirty()]]></c>, or pass appropriate flags to
623
<c><![CDATA[ei_reg_dump()]]></c>.</p>
added
removed
lib/erl_interface/doc/src/erl_interface.xml
