| Subject: | Checking status of zmq calls: documentation, perl-way vs. raw libzmq interface |
| Date: | Thu, 16 Feb 2012 18:32:49 +0100 |
| To: | bug-ZeroMQ [...] rt.cpan.org |
| From: | Mark Martinec <Mark.Martinec [...] ijs.si> |
Using ZeroMQ-0.20, perl 5.14.2, zmq-2.1.11, on a FreeBSD.
The ZeroMQ perl module offers two interfaces: the low-level ZeroMQ::Raw,
and a more perlish OO interface. The low level interface just passes
status returns from the library calls, and this is documented in the
POD page. No problem with that.
The higher level / object-oriented interface however does not document
what are the results of method calls. Hence the application programmer
has no right to check the status results - or if one does so nevertheless,
he is faced with inconsistent behaviour.
One would expect the higher-level interface would provide the more
perl way of returning success/failure status. For example the following
sample code shows what I would expect from the ZeroMQ module:
#!/usr/bin/perl
use strict;
use warnings;
use ZeroMQ qw(:all);
my $ctx = ZeroMQ::Context->new
or die "Error creating ZeroMQ context: $!";
$ctx->ctxt
or die "Error creating ZeroMQ context (2): $!";
my $sock = $ctx->socket(ZMQ_PUB)
or die "Error creating ZeroMQ socket: $!";
$sock->connect('tcp://127.0.0.1:23232')
or warn "Error connecting ZeroMQ socket: $!";
$sock->setsockopt(ZMQ_HWM, 500)
or warn "Error setting highwater mark on a ZeroMQ socket: $!";
$sock->send("test")
or warn "Error sending a ZeroMQ message: $!";
$sock->close
or warn "Error closing ZeroMQ socket: $!";
What happens is:
Error connecting ZeroMQ socket: at ./amavis-zmq-test.pl line 15.
Error setting highwater mark on a ZeroMQ socket: Invalid argument at ./amavis-zmq-test.pl line 18.
Error sending a ZeroMQ message: Resource temporarily unavailable at ./amavis-zmq-test.pl line 21.
Error closing ZeroMQ socket: Resource temporarily unavailable at ./amavis-zmq-test.pl line 24.
So, the ZeroMQ::Context->new and $ctx->socket behave in an expected way,
while the connect, setsockopt, send and close do not convert a low-level
return status of a call into a perl-style: undef for a failure with error in $!,
and a true for a success.
As the return values are currently not documented, there is still a chance
of changing the current behaviour: the OO methods should translate a raw
library result code into undef/true, and this should be clearly documented.
This should make it compatible with classical connect/setsockopt/send/close
and similar operations on traditional sockets.
Alternatively (less desirable), please do document the current behaviour
and point out what is the recommended way for an application to test
the status returns.
Regards
Mark