1ZACTOR(3) CZMQ Manual ZACTOR(3)
2
6 zactor - Class for simple actor framework
7
9 // This is a stable class, and may not change except for emergencies. It
10 // is provided in stable builds.
11 // This class has draft methods, which may change over time. They are not
12 // in stable releases, by default. Use --enable-drafts to enable.
13 // Actors get a pipe and arguments from caller
14 typedef void (zactor_fn) (
15 zsock_t *pipe, void *args);
16 // Create a new actor passing arbitrary arguments reference.
18 CZMQ_EXPORT zactor_t *
19 zactor_new (zactor_fn task, void *args);
20 // Destroy an actor.
22 CZMQ_EXPORT void
23 zactor_destroy (zactor_t **self_p);
24 // Send a zmsg message to the actor, take ownership of the message
26 // and destroy when it has been sent.
27 CZMQ_EXPORT int
28 zactor_send (zactor_t *self, zmsg_t **msg_p);
29 // Receive a zmsg message from the actor. Returns NULL if the actor
31 // was interrupted before the message could be received, or if there
32 // was a timeout on the actor.
33 // Caller owns return value and must destroy it when done.
34 CZMQ_EXPORT zmsg_t *
35 zactor_recv (zactor_t *self);
36 // Probe the supplied object, and report if it looks like a zactor_t.
38 CZMQ_EXPORT bool
39 zactor_is (void *self);
40 // Probe the supplied reference. If it looks like a zactor_t instance,
42 // return the underlying libzmq actor handle; else if it looks like
43 // a libzmq actor handle, return the supplied value.
44 CZMQ_EXPORT void *
45 zactor_resolve (void *self);
46 // Return the actor's zsock handle. Use this when you absolutely need
48 // to work with the zsock instance rather than the actor.
49 CZMQ_EXPORT zsock_t *
50 zactor_sock (zactor_t *self);
51 // Self test of this class.
53 CZMQ_EXPORT void
54 zactor_test (bool verbose);
55 #ifdef CZMQ_BUILD_DRAFT_API
57 // Function to be called on zactor_destroy. Default behavior is to send zmsg_t with string "$TERM" in a first frame.
58 //
59 // An example - to send $KTHXBAI string
60 //
61 // if (zstr_send (self, "$KTHXBAI") == 0)
62 // zsock_wait (self);
63 typedef void (zactor_destructor_fn) (
64 zactor_t *self);
65 // *** Draft method, for development use, may change without warning ***
67 // Change default destructor by custom function. Actor MUST be able to handle new message instead of default $TERM.
68 CZMQ_EXPORT void
69 zactor_set_destructor (zactor_t *self, zactor_destructor_fn destructor);
70 #endif // CZMQ_BUILD_DRAFT_API
72 Please add '@interface' section in './../src/zactor.c'.
73
75 The zactor class provides a simple actor framework. It replaces the
76 CZMQ zthread class, which had a complex API that did not fit the CLASS
77 standard. A CZMQ actor is implemented as a thread plus a PAIR-PAIR
78 pipe. The constructor and destructor are always synchronized, so the
79 caller can be sure all resources are created, and destroyed, when these
80 calls complete. (This solves a major problem with zthread, that a
81 caller could not be sure when a child thread had finished.)
82 A zactor_t instance acts like a zsock_t and you can pass it to any CZMQ
84 method that would take a zsock_t argument, including methods in zframe,
85 zmsg, zstr, and zpoller. (zloop somehow escaped and needs catching.)
86 An actor function MUST call zsock_signal (pipe) when initialized and
88 MUST listen to pipe and exit on $TERM command.
89 Please add @discuss section in ./../src/zactor.c.
91
93 From zactor_test method.
94 zactor_t *actor = zactor_new (echo_actor, "Hello, World");
96 assert (actor);
97 zstr_sendx (actor, "ECHO", "This is a string", NULL);
98 char *string = zstr_recv (actor);
99 assert (streq (string, "This is a string"));
100 freen (string);
101 zactor_destroy (&actor);
102 // custom destructor
104 // KTHXBAI_actor ends on "$KTHXBAI" string
105 zactor_t *KTHXBAI = zactor_new (KTHXBAI_actor, NULL);
106 assert (KTHXBAI);
107 // which is the one sent by KTHXBAI_destructor
108 zactor_set_destructor (KTHXBAI, KTHXBAI_destructor);
109 zactor_destroy (&KTHXBAI);
110 // custom destructor
112 // destructor using bsend/brecv
113 zactor_t *BSEND = zactor_new (BSEND_actor, NULL);
114 assert (BSEND);
115 zactor_set_destructor (BSEND, BSEND_destructor);
116 zactor_destroy (&BSEND);
117 #if defined (__WINDOWS__)
118 zsys_shutdown();
119 #endif
120
123 The czmq manual was written by the authors in the AUTHORS file.
124
126 Main web site:
127 Report bugs to the email <zeromq-dev@lists.zeromq.org[1]>
129
131 Copyright (c) the Contributors as noted in the AUTHORS file. This file
132 is part of CZMQ, the high-level C binding for 0MQ:
133 http://czmq.zeromq.org. This Source Code Form is subject to the terms
134 of the Mozilla Public License, v. 2.0. If a copy of the MPL was not
135 distributed with this file, You can obtain one at
136 http://mozilla.org/MPL/2.0/. LICENSE included with the czmq
137 distribution.
138
140 1. zeromq-dev@lists.zeromq.org
141 mailto:zeromq-dev@lists.zeromq.org
142CZMQ 4.2.1 01/19/2023 ZACTOR(3)