'\" t .\" Title: zthread .\" Author: [see the "AUTHORS" section] .\" Generator: DocBook XSL Stylesheets v1.78.1 .\" 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