~ubuntu-branches/ubuntu/saucy/zeromq3/saucy

The \fIzmq_socket_monitor()\fR function shall spawn a \fIPAIR\fR socket that publishes socket state changes (events) over the inproc:// transport to a given endpoint\&. Messages are \fIzmq_event_t\fR structs\&. It\(cqs recommended to connect via a \fIPAIR\fR socket in another application thread and handle monitoring events there\&. It\(cqs possible to also supply a bitmask (\fIZMQ_EVENT_ALL\fR or any combination of the \fIZMQ_EVENT_*\fR constants) of the events you\(cqre interested in\&.

.sp

.if n \{\

.RS 4

.\}

.nf

// monitoring thread

static void *req_socket_monitor (void *ctx)

{

zmq_event_t event;

int rc;

void *s = zmq_socket (ctx, ZMQ_PAIR);

assert (s);

rc = zmq_connect (s, "inproc://monitor\&.req");

assert (rc == 0);

while (true) {

zmq_msg_t msg;

zmq_msg_init (&msg);

rc = zmq_recvmsg (s, &msg, 0);

if (rc == \-1 && zmq_errno() == ETERM) break;

assert (rc != \-1);

memcpy (&event, zmq_msg_data (&msg), sizeof (event));

switch (event\&.event) {

case ZMQ_EVENT_CONNECTED:

// handle socket connected event

break;

case ZMQ_EVENT_CLOSED:

// handle socket closed event

break;

}

zmq_close (s);

return NULL;

}

// register a monitor endpoint for all socket events

rc = zmq_socket_monitor (req, "inproc://monitor\&.req", ZMQ_EVENT_ALL);

assert (rc == 0);

// spawn a monitoring thread

rc = pthread_create (&threads [0], NULL, req_socket_monitor, ctx);

assert (rc == 0);

.fi

.if n \{\

.RE

.\}

.sp

Only connection oriented (tcp and ipc) transports are supported in this initial implementation\&.

.sp

Supported events are:

.SS "ZMQ_EVENT_CONNECTED: connection established"

.sp

The \fIZMQ_EVENT_CONNECTED\fR event triggers when a connection has been established to a remote peer\&. This can happen either synchronous or asynchronous\&.

.PP

\fBEvent metadata:\fR.

.sp

.if n \{\

.RS 4

.\}

.nf

data\&.connected\&.addr // peer address

100

data\&.connected\&.fd // socket descriptor

101

.fi

102

.if n \{\

103

.RE

104

.\}

105

.sp

106

.SS "ZMQ_EVENT_CONNECT_DELAYED: synchronous connect failed, it\(cqs being polled"

107

.sp

108

The \fIZMQ_EVENT_CONNECT_DELAYED\fR event triggers when an immediate connection attempt is delayed and it\(cqs completion\(cqs being polled for\&.

109

.PP

110

\fBEvent metadata:\fR.

111

.sp

112

.if n \{\

113

.RS 4

114

.\}

115

.nf

116

data\&.connect_delayed\&.addr // peer address

117

data\&.connect_delayed\&.err // errno value

118

.fi

119

.if n \{\

120

.RE

121

.\}

122

.sp

123

.SS "ZMQ_EVENT_CONNECT_RETRIED: asynchronous connect / reconnection attempt"

124

.sp

125

The \fIZMQ_EVENT_CONNECT_RETRIED\fR event triggers when a connection attempt is being handled by reconnect timer\&. The reconnect interval\(cqs recomputed for each attempt\&.

126

.PP

127

\fBEvent metadata:\fR.

128

.sp

129

.if n \{\

130

.RS 4

131

.\}

132

.nf

133

data\&.connect_retried\&.addr // peer address

134

data\&.connect_retried\&.interval // computed reconnect interval

135

.fi

136

.if n \{\

137

.RE

138

.\}

139

.sp

140

.SS "ZMQ_EVENT_LISTENING: socket bound to an address, ready to accept connections"

141

.sp

142

The \fIZMQ_EVENT_LISTENING\fR event triggers when a socket\(cqs successfully bound to a an interface\&.

143

.PP

144

\fBEvent metadata:\fR.

145

.sp

146

.if n \{\

147

.RS 4

148

.\}

149

.nf

150

data\&.listening\&.addr // listen address

151

data\&.listening\&.fd // socket descriptor

152

.fi

153

.if n \{\

154

.RE

155

.\}

156

.sp

157

.SS "ZMQ_EVENT_BIND_FAILED: socket could not bind to an address"

158

.sp

159

The \fIZMQ_EVENT_BIND_FAILED\fR event triggers when a socket could not bind to a given interface\&.

160

.PP

161

\fBEvent metadata:\fR.

162

.sp

163

.if n \{\

164

.RS 4

165

.\}

166

.nf

167

data\&.bind_failed\&.addr // listen address

168

data\&.bind_failed\&.err // errno value

169

.fi

170

.if n \{\

171

.RE

172

.\}

173

.sp

174

.SS "ZMQ_EVENT_ACCEPTED: connection accepted to bound interface"

175

.sp

176

The \fIZMQ_EVENT_ACCEPTED\fR event triggers when a connection from a remote peer has been established with a socket\(cqs listen address\&.

177

.PP

178

\fBEvent metadata:\fR.

179

.sp

180

.if n \{\

181

.RS 4

182

.\}

183

.nf

184

data\&.accepted\&.addr // listen address

185

data\&.accepted\&.fd // socket descriptor

186

.fi

187

.if n \{\

188

.RE

189

.\}

190

.sp

191

.SS "ZMQ_EVENT_ACCEPT_FAILED: could not accept client connection"

192

.sp

193

The \fIZMQ_EVENT_ACCEPT_FAILED\fR event triggers when a connection attempt to a socket\(cqs bound address fails\&.

194

.PP

195

\fBEvent metadata:\fR.

196

.sp

197

.if n \{\

198

.RS 4

199

.\}

200

.nf

201

data\&.accept_failed\&.addr // listen address

202

data\&.accept_failed\&.err // errno value

203

.fi

204

.if n \{\

205

.RE

206

.\}

207

.sp

208

.SS "ZMQ_EVENT_CLOSED: connection closed"

209

.sp

210

The \fIZMQ_EVENT_CLOSED\fR event triggers when a connection\(cqs underlying descriptor has been closed\&.

211

.PP

212

\fBEvent metadata:\fR.

213

.sp

214

.if n \{\

215

.RS 4

216

.\}

217

.nf

218

data\&.closed\&.addr // address

219

data\&.closed\&.fd // socket descriptor

220

.fi

221

.if n \{\

222

.RE

223

.\}

224

.sp

225

.SS "ZMQ_EVENT_CLOSE_FAILED: connection couldn\(cqt be closed"

226

.sp

227

The \fIZMQ_EVENT_CLOSE_FAILED\fR event triggers when a descriptor could not be released back to the OS\&.

228

.PP

229

\fBEvent metadata:\fR.

230

.sp

231

.if n \{\

232

.RS 4

233

.\}

234

.nf

235

data\&.close_failed\&.addr // address

236

data\&.close_failed\&.err // errno value

237

.fi

238

.if n \{\

239

.RE

240

.\}

241

.sp

242

.SS "ZMQ_EVENT_DISCONNECTED: broken session"

243

.sp

244

The \fIZMQ_EVENT_DISCONNECTED\fR event triggers when the stream engine (tcp and ipc specific) detects a corrupted / broken session\&.

245

.PP

246

\fBEvent metadata:\fR.

247

.sp

248

.if n \{\

249

.RS 4

250

.\}

251

.nf

252

data\&.disconnected\&.addr // address

253

data\&.disconnected\&.fd // socket descriptor

254

.fi

255

.if n \{\

256

.RE

257

.\}

258

.sp

259

.SH "RETURN VALUE"

260

.sp

261

The \fIzmq_socket_monitor()\fR function returns a value of 0 or greater if successful\&. Otherwise it returns \-1 and sets \fIerrno\fR to one of the values defined below\&.

262

.SH "ERRORS"

263

.PP

264

\fBETERM\fR

265

.RS 4

266

The 0MQ

267

\fIcontext\fR

268

associated with the specified

269

\fIsocket\fR

270

was terminated\&.

271

.RE

272

.PP

273

\fBEPROTONOSUPPORT\fR

274

.RS 4

275

The requested

276

\fItransport\fR

277

protocol is not supported\&. Monitor sockets are required to use the inproc:// transport\&.

278

.RE

279

.PP

280

\fBEINVAL\fR

281

.RS 4

282

The endpoint supplied is invalid\&.

283

.RE

284

.SH "EXAMPLE"

285

.PP

286

\fBObserving a REP socket\(cqs connection state\fR.

287

.sp

288

.if n \{\

289

.RS 4

290

.\}

291

.nf

292

// REP socket monitor thread

293

static void *rep_socket_monitor (void *ctx)

294

{

295

zmq_event_t event;

296

int rc;

297

298

void *s = zmq_socket (ctx, ZMQ_PAIR);

299

assert (s);

300

301

rc = zmq_connect (s, "inproc://monitor\&.rep");

302

assert (rc == 0);

303

while (true) {

304

zmq_msg_t msg;

305

zmq_msg_init (&msg);

306

rc = zmq_recvmsg (s, &msg, 0);

307

if (rc == \-1 && zmq_errno() == ETERM) break;

308

assert (rc != \-1);

309

memcpy (&event, zmq_msg_data (&msg), sizeof (event));

310

switch (event\&.event) {

311

case ZMQ_EVENT_LISTENING:

312

printf ("listening socket descriptor %d\en", event\&.data\&.listening\&.fd);

313

printf ("listening socket address %s\en", event\&.data\&.listening\&.addr);

314

break;

315

case ZMQ_EVENT_ACCEPTED:

316

printf ("accepted socket descriptor %d\en", event\&.data\&.accepted\&.fd);

317

printf ("accepted socket address %s\en", event\&.data\&.accepted\&.addr);

318

break;

319

case ZMQ_EVENT_CLOSE_FAILED:

320

printf ("socket close failure error code %d\en", event\&.data\&.close_failed\&.err);

321

printf ("socket address %s\en", event\&.data\&.close_failed\&.addr);

322

break;

323

case ZMQ_EVENT_CLOSED:

324

printf ("closed socket descriptor %d\en", event\&.data\&.closed\&.fd);

325

printf ("closed socket address %s\en", event\&.data\&.closed\&.addr);

326

break;

327

case ZMQ_EVENT_DISCONNECTED:

328

printf ("disconnected socket descriptor %d\en", event\&.data\&.disconnected\&.fd);

329

printf ("disconnected socket address %s\en", event\&.data\&.disconnected\&.addr);

330

break;

331

}

332

zmq_msg_close (&msg);

333

}

334

zmq_close (s);

335

return NULL;

336

}

337

338

339

// Create the infrastructure

340

void *ctx = zmq_init (1);

341

assert (ctx);

342

343

// REP socket

344

rep = zmq_socket (ctx, ZMQ_REP);

345

assert (rep);

346

347

// REP socket monitor, all events

348

rc = zmq_socket_monitor (rep, "inproc://monitor\&.rep", ZMQ_EVENT_ALL);

349

assert (rc == 0);

350

rc = pthread_create (&threads [0], NULL, rep_socket_monitor, ctx);

351

assert (rc == 0);

352

353

rc = zmq_bind (rep, addr);

354

assert (rc == 0);

355

356

// Allow some time for event detection

357

zmq_sleep (1);

358

359

// Close the REP socket

360

rc = zmq_close (rep);

361

assert (rc == 0);

362

363

zmq_term (ctx);

364

.fi

365

.if n \{\

366

.RE

367

.\}

368

.sp

369

.SH "SEE ALSO"

370

.sp

371

\fBzmq\fR(7)

372

.SH "AUTHORS"

373

.sp

374

This 0MQ manual page was written by Lourens Naud\('e <\m[blue]\fBlourens@methodmissing\&.com\fR\m[]\&\s-2\u[1]\d\s+2>

375

.SH "NOTES"

376

.IP " 1." 4

377

lourens@methodmissing.com

378

.RS 4

379

\%mailto:lourens@methodmissing.com

380

.RE

Older »