You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
128 lines
4.8 KiB
128 lines
4.8 KiB
6 years ago
|
'\" t
|
||
|
|
.\" Title: zactor
|
||
|
|
.\" Author: [see the "AUTHORS" section]
|
||
|
|
.\" Generator: DocBook XSL Stylesheets v1.76.1 <http://docbook.sf.net/>
|
||
|
|
.\" Date: 12/31/2016
|
||
|
|
.\" Manual: CZMQ Manual
|
||
|
|
.\" Source: CZMQ 4.0.2
|
||
|
|
.\" Language: English
|
||
|
|
.\"
|
||
|
|
.TH "ZACTOR" "3" "12/31/2016" "CZMQ 4\&.0\&.2" "CZMQ Manual"
|
||
|
|
.\" -----------------------------------------------------------------
|
||
|
|
.\" * Define some portability stuff
|
||
|
|
.\" -----------------------------------------------------------------
|
||
|
|
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||
|
|
.\" http://bugs.debian.org/507673
|
||
|
|
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
|
||
|
|
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||
|
|
.ie \n(.g .ds Aq \(aq
|
||
|
|
.el .ds Aq '
|
||
|
|
.\" -----------------------------------------------------------------
|
||
|
|
.\" * set default formatting
|
||
|
|
.\" -----------------------------------------------------------------
|
||
|
|
.\" disable hyphenation
|
||
|
|
.nh
|
||
|
|
.\" disable justification (adjust text to left margin only)
|
||
|
|
.ad l
|
||
|
|
.\" -----------------------------------------------------------------
|
||
|
|
.\" * MAIN CONTENT STARTS HERE *
|
||
|
|
.\" -----------------------------------------------------------------
|
||
|
|
.SH "NAME"
|
||
|
|
zactor \- simple actor framework
|
||
|
|
.SH "SYNOPSIS"
|
||
|
|
.sp
|
||
|
|
.nf
|
||
|
|
// This is a stable class, and may not change except for emergencies\&. It
|
||
|
|
// is provided in stable builds\&.
|
||
|
|
// 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\*(Aqs 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);
|
||
|
|
|
||
|
|
Please add \*(Aq@interface\*(Aq section in \*(Aq\&./\&.\&./src/zactor\&.c\*(Aq\&.
|
||
|
|
.fi
|
||
|
|
.SH "DESCRIPTION"
|
||
|
|
.sp
|
||
|
|
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\&.)
|
||
|
|
.sp
|
||
|
|
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\&.)
|
||
|
|
.sp
|
||
|
|
An actor function MUST call zsock_signal (pipe) when initialized and MUST listen to pipe and exit on $TERM command\&.
|
||
|
|
.sp
|
||
|
|
Please add \fI@discuss\fR section in \fI\&./\&.\&./src/zactor\&.c\fR\&.
|
||
|
|
.SH "EXAMPLE"
|
||
|
|
.PP
|
||
|
|
\fBFrom zactor_test method\fR.
|
||
|
|
.sp
|
||
|
|
.if n \{\
|
||
|
|
.RS 4
|
||
|
|
.\}
|
||
|
|
.nf
|
||
|
|
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"));
|
||
|
|
free (string);
|
||
|
|
zactor_destroy (&actor);
|
||
|
|
.fi
|
||
|
|
.if n \{\
|
||
|
|
.RE
|
||
|
|
.\}
|
||
|
|
.sp
|
||
|
|
.SH "AUTHORS"
|
||
|
|
.sp
|
||
|
|
The czmq manual was written by the authors in the AUTHORS file\&.
|
||
|
|
.SH "RESOURCES"
|
||
|
|
.sp
|
||
|
|
Main web site: \m[blue]\fB\%\fR\m[]
|
||
|
|
.sp
|
||
|
|
Report bugs to the email <\m[blue]\fBzeromq\-dev@lists\&.zeromq\&.org\fR\m[]\&\s-2\u[1]\d\s+2>
|
||
|
|
.SH "COPYRIGHT"
|
||
|
|
.sp
|
||
|
|
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\&.
|
||
|
|
.SH "NOTES"
|
||
|
|
.IP " 1." 4
|
||
|
|
zeromq-dev@lists.zeromq.org
|
||
|
|
.RS 4
|
||
|
|
\%mailto:zeromq-dev@lists.zeromq.org
|
||
|
|
.RE
|