Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help 
ZACTOR(3)			  CZMQ Manual			     ZACTOR(3)

NAME
       zactor -	Class for simple actor framework

SYNOPSIS
       //  This	is a stable class, and may not change except for emergencies. It
       //  is provided in stable builds.
       //  This	class has draft	methods, which may change over time. They are not
       //  in stable releases, by default. Use --enable-drafts to enable.
       // Actors get a pipe and	arguments from caller
       typedef void (zactor_fn)	(
	   zsock_t *pipe, void *args);

       //  Create a new	actor passing arbitrary	arguments reference.
       CZMQ_EXPORT zactor_t *
	   zactor_new (zactor_fn task, void *args);

       //  Destroy an actor.
       CZMQ_EXPORT void
	   zactor_destroy (zactor_t **self_p);

       //  Send	a zmsg message to the actor, take ownership of the message
       //  and destroy when it has been	sent.
       CZMQ_EXPORT int
	   zactor_send (zactor_t *self,	zmsg_t **msg_p);

       //  Receive a zmsg message from the actor. Returns NULL if the actor
       //  was interrupted before the message could be received, or if there
       //  was a timeout on the	actor.
       //  Caller owns return value and	must destroy it	when done.
       CZMQ_EXPORT zmsg_t *
	   zactor_recv (zactor_t *self);

       //  Probe the supplied object, and report if it looks like a zactor_t.
       CZMQ_EXPORT bool
	   zactor_is (void *self);

       //  Probe the supplied reference. If it looks like a zactor_t instance,
       //  return the underlying libzmq	actor handle; else if it looks like
       //  a libzmq actor handle, return the supplied value.
       CZMQ_EXPORT void	*
	   zactor_resolve (void	*self);

       //  Return the actor's zsock handle. Use	this when you absolutely need
       //  to work with	the zsock instance rather than the actor.
       CZMQ_EXPORT zsock_t *
	   zactor_sock (zactor_t *self);

       //  Self	test of	this class.
       CZMQ_EXPORT void
	   zactor_test (bool verbose);

       #ifdef CZMQ_BUILD_DRAFT_API
       // Function to be called	on zactor_destroy. Default behavior is to send zmsg_t with string "$TERM" in a first frame.
       //
       // An example - to send $KTHXBAI	string
       //
       //     if (zstr_send (self, "$KTHXBAI") == 0)
       //	  zsock_wait (self);
       typedef void (zactor_destructor_fn) (
	   zactor_t *self);

       //  *** Draft method, for development use, may change without warning ***
       //  Change default destructor by	custom function. Actor MUST be able to handle new message instead of default $TERM.
       CZMQ_EXPORT void
	   zactor_set_destructor (zactor_t *self, zactor_destructor_fn destructor);

       #endif // CZMQ_BUILD_DRAFT_API
       Please add '@interface' section in './../src/zactor.c'.

DESCRIPTION
       The zactor class	provides a simple actor	framework. It replaces the
       CZMQ zthread class, which had a complex API that	did not	fit the	CLASS
       standard. A CZMQ	actor is implemented as	a thread plus a	PAIR-PAIR
       pipe. The constructor and destructor are	always synchronized, so	the
       caller can be sure all resources	are created, and destroyed, when these
       calls complete. (This solves a major problem with zthread, that a
       caller could not	be sure	when a child thread had	finished.)

       A zactor_t instance acts	like a zsock_t and you can pass	it to any CZMQ
       method that would take a	zsock_t	argument, including methods in zframe,
       zmsg, zstr, and zpoller.	(zloop somehow escaped and needs catching.)

       An actor	function MUST call zsock_signal	(pipe) when initialized	and
       MUST listen to pipe and exit on $TERM command.

       Please add @discuss section in ./../src/zactor.c.

EXAMPLE
       From zactor_test	method.

	   zactor_t *actor = zactor_new	(echo_actor, "Hello, World");
	   assert (actor);
	   zstr_sendx (actor, "ECHO", "This is a string", NULL);
	   char	*string	= zstr_recv (actor);
	   assert (streq (string, "This	is a string"));
	   freen (string);
	   zactor_destroy (&actor);

	   // custom destructor
	   // KTHXBAI_actor ends on "$KTHXBAI" string
	   zactor_t *KTHXBAI = zactor_new (KTHXBAI_actor, NULL);
	   assert (KTHXBAI);
	   // which is the one sent by KTHXBAI_destructor
	   zactor_set_destructor (KTHXBAI, KTHXBAI_destructor);
	   zactor_destroy (&KTHXBAI);

	   // custom destructor
	   // destructor using bsend/brecv
	   zactor_t *BSEND = zactor_new	(BSEND_actor, NULL);
	   assert (BSEND);
	   zactor_set_destructor (BSEND, BSEND_destructor);
	   zactor_destroy (&BSEND);
	   #if defined (__WINDOWS__)
	   zsys_shutdown();
	   #endif

AUTHORS
       The czmq	manual was written by the authors in the AUTHORS file.

RESOURCES
       Main web	site:

       Report bugs to the email	<zeromq-dev@lists.zeromq.org[1]>

COPYRIGHT
       Copyright (c) the Contributors as noted in the AUTHORS file. This file
       is part of CZMQ,	the high-level C binding for 0MQ:
       http://czmq.zeromq.org. This Source Code	Form is	subject	to the terms
       of the Mozilla Public License, v. 2.0. If a copy	of the MPL was not
       distributed with	this file, You can obtain one at
       http://mozilla.org/MPL/2.0/. LICENSE included with the czmq
       distribution.

NOTES
	1. zeromq-dev@lists.zeromq.org
	   mailto:zeromq-dev@lists.zeromq.org

CZMQ 4.2.1			  11/01/2025			     ZACTOR(3)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=zactor&sektion=3&manpath=FreeBSD+Ports+15.0>

home | help