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.
149 lines
6.2 KiB
149 lines
6.2 KiB
5 years ago
|
'\" t
|
||
|
|
.\" Title: zthread
|
||
|
|
.\" Author: [see the "AUTHORS" section]
|
||
|
|
.\" Generator: DocBook XSL Stylesheets v1.78.1 <http://docbook.sf.net/>
|
||
|
|
.\" Date: 09/14/2016
|
||
|
|
.\" Manual: CZMQ Manual
|
||
|
|
.\" Source: CZMQ 3.0.2
|
||
|
|
.\" Language: English
|
||
|
|
.\"
|
||
|
|
.TH "ZTHREAD" "3" "09/14/2016" "CZMQ 3\&.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"
|
||
|
|
zthread \- working with system threads (deprecated)
|
||
|
|
.SH "SYNOPSIS"
|
||
|
|
.sp
|
||
|
|
.nf
|
||
|
|
// Detached threads follow POSIX pthreads API
|
||
|
|
typedef void *(zthread_detached_fn) (void *args);
|
||
|
|
|
||
|
|
// Attached threads get context and pipe from parent
|
||
|
|
typedef void (zthread_attached_fn) (void *args, zctx_t *ctx, void *pipe);
|
||
|
|
|
||
|
|
// Create a detached thread\&. A detached thread operates autonomously
|
||
|
|
// and is used to simulate a separate process\&. It gets no ctx, and no
|
||
|
|
// pipe\&.
|
||
|
|
CZMQ_EXPORT int
|
||
|
|
zthread_new (zthread_detached_fn *thread_fn, void *args);
|
||
|
|
|
||
|
|
// Create an attached thread\&. An attached thread gets a ctx and a PAIR
|
||
|
|
// pipe back to its parent\&. It must monitor its pipe, and exit if the
|
||
|
|
// pipe becomes unreadable\&. Do not destroy the ctx, the thread does this
|
||
|
|
// automatically when it ends\&.
|
||
|
|
CZMQ_EXPORT void *
|
||
|
|
zthread_fork (zctx_t *ctx, zthread_attached_fn *thread_fn, void *args);
|
||
|
|
|
||
|
|
// Self test of this class
|
||
|
|
CZMQ_EXPORT void
|
||
|
|
zthread_test (bool verbose);
|
||
|
|
.fi
|
||
|
|
.SH "DESCRIPTION"
|
||
|
|
.sp
|
||
|
|
The zthread class wraps OS thread creation\&. It creates detached threads that look like normal OS threads, or attached threads that share the caller\(cqs 0MQ context, and get an inproc pipe to talk back to the parent thread\&. Detached threads create their own 0MQ contexts as needed\&. NOTE: this class is deprecated in favor of zactor\&.
|
||
|
|
.sp
|
||
|
|
We have several use cases for multiple threads\&. One is to simulate many processes, so we can test 0MQ designs and flows more easily\&. Another is to create APIs that can send and receive 0MQ messages in the background\&.
|
||
|
|
.sp
|
||
|
|
zthread solves these two use cases separately, using the zthread_new and zthead_fork methods respectively\&. These methods wrap the native system calls needed to start threads, so your code can remain fully portable\&.
|
||
|
|
.sp
|
||
|
|
Detached threads follow the POSIX pthreads API; they accept a void * argument and return a void * result (always NULL in our case)\&.
|
||
|
|
.sp
|
||
|
|
Attached thread receive a void * argument, a zctx_t context, and a pipe socket\&. The pipe socket is a PAIR socket that is connected back to the caller\&. When you call zthread_fork, it returns you a PAIR socket that is the other end of this pipe\&. Thus attached threads can talk back to their parent threads over the pipe\&. We use this very heavily when making so\-called "asynchronous" APIs, which you can see in the Guide examples like \fIclone\fR\&.
|
||
|
|
.sp
|
||
|
|
To recap some rules about threading: do not share sockets between threads or your code will crash\&. You can migrate a socket from one thread to a child thread, if you stop using it in the parent thread immediately after creating the child thread\&. If you want to connect sockets over inproc:// they must share the same 0MQ context, i\&.e\&. be attached threads\&. You should always use zthread_fork to create an attached thread; it is not sufficient to pass a zctx_t structure to a detached thread (this will crash)\&.
|
||
|
|
.sp
|
||
|
|
If you want to communicate over ipc:// or tcp:// you may be sharing the same context, or use separate contexts\&. Thus, every detached thread usually starts by creating its own zctx_t instance\&.
|
||
|
|
.SH "EXAMPLE"
|
||
|
|
.PP
|
||
|
|
\fBFrom zthread_test method\fR.
|
||
|
|
.sp
|
||
|
|
.if n \{\
|
||
|
|
.RS 4
|
||
|
|
.\}
|
||
|
|
.nf
|
||
|
|
static void *
|
||
|
|
s_test_detached (void *args)
|
||
|
|
{
|
||
|
|
// Create a socket to check it\*(Aqll be automatically deleted
|
||
|
|
zctx_t *ctx = zctx_new ();
|
||
|
|
assert (ctx);
|
||
|
|
|
||
|
|
void *push = zsocket_new (ctx, ZMQ_PUSH);
|
||
|
|
assert (push);
|
||
|
|
zctx_destroy (&ctx);
|
||
|
|
return NULL;
|
||
|
|
}
|
||
|
|
|
||
|
|
static void
|
||
|
|
s_test_attached (void *args, zctx_t *ctx, void *pipe)
|
||
|
|
{
|
||
|
|
// Create a socket to check it\*(Aqll be automatically deleted
|
||
|
|
zsocket_new (ctx, ZMQ_PUSH);
|
||
|
|
assert (ctx);
|
||
|
|
// Wait for our parent to ping us, and pong back
|
||
|
|
char *ping = zstr_recv (pipe);
|
||
|
|
assert (ping);
|
||
|
|
zstr_free (&ping);
|
||
|
|
zstr_send (pipe, "pong");
|
||
|
|
}
|
||
|
|
|
||
|
|
zctx_t *ctx = zctx_new ();
|
||
|
|
assert (ctx);
|
||
|
|
int rc = 0;
|
||
|
|
|
||
|
|
// Create a detached thread, let it run
|
||
|
|
rc = zthread_new (s_test_detached, NULL);
|
||
|
|
assert (rc == 0);
|
||
|
|
zclock_sleep (100);
|
||
|
|
|
||
|
|
// Create an attached thread, check it\*(Aqs safely alive
|
||
|
|
void *pipe = zthread_fork (ctx, s_test_attached, NULL);
|
||
|
|
assert (pipe);
|
||
|
|
zstr_send (pipe, "ping");
|
||
|
|
char *pong = zstr_recv (pipe);
|
||
|
|
assert (pong);
|
||
|
|
assert (streq (pong, "pong"));
|
||
|
|
zstr_free (&pong);
|
||
|
|
|
||
|
|
// Everything should be cleanly closed now
|
||
|
|
zctx_destroy (&ctx);
|
||
|
|
.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) 1991\-2012 iMatix Corporation \-\- http://www\&.imatix\&.com Copyright other 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
|