[libmessage-passing-zeromq-perl] 49/78: More docs
Jonas Smedegaard
js at alioth.debian.org
Mon Sep 30 09:28:25 UTC 2013
This is an automated email from the git hooks/post-receive script.
js pushed a commit to branch master
in repository libmessage-passing-zeromq-perl.
commit 886c9199329413052f591c7d08e223ecc3c2c644
Author: Tomas Doran <bobtfish at bobtfish.net>
Date: Sat Jun 9 16:44:48 2012 +0100
More docs
---
Changes | 2 ++
README | 59 +++++++++++++++++++++++++------
lib/Message/Passing/Input/ZeroMQ.pm | 13 +++++++
lib/Message/Passing/Output/ZeroMQ.pm | 15 +++++---
lib/Message/Passing/ZeroMQ.pm | 63 ++++++++++++++++++++++++++++------
5 files changed, 127 insertions(+), 25 deletions(-)
diff --git a/Changes b/Changes
index 1c744f3..10cd476 100644
--- a/Changes
+++ b/Changes
@@ -1,3 +1,5 @@
+ - Improve documentation.
+
0.004
- Changes to match up with Message::Passing 0.006
diff --git a/README b/README
index 0fbb8a1..f8b66b6 100644
--- a/README
+++ b/README
@@ -3,11 +3,11 @@ NAME
SYNOPSIS
# Terminal 1:
- $ message-passing --input STDIN --output ZeroMQ --output_options '{"connect":"tcp://127.0.0.1:5558"}'
+ $ message-passing --input STDIN --output ZeroMQ --output_options '{"connect":"tcp://127.0.0.1:5552"}'
{"data":{"some":"data"},"@metadata":"value"}
# Terminal 2:
- $ message-passing --output STDOUT --input ZeroMQ --input_options '{"socket_bind":"tcp://*:5558"}'
+ $ message-passing --output STDOUT --input ZeroMQ --input_options '{"socket_bind":"tcp://*:5552"}'
{"data":{"some":"data"},"@metadata":"value"}
DESCRIPTION
@@ -36,22 +36,33 @@ DESCRIPTION
HOW TO USE
In your application emitting messages, you can either use
- Message::Passing::Output::ZeroMQ directly, of you can use it via
+ Message::Passing::Output::ZeroMQ directly, or you can use it via
Log::Dispatch::Message::Passing.
- # FIXME - Example code, including overriding IP to connect to here
+ use Log::Dispatch;
+ use Log::Dispatch::Message::Passing;
+ use Message::Passing::Output::ZeroMQ;
+ use Message::Passing::Filter::Encode::JSON;
+
+ my $log = Log::Dispatch->new;
+
+ $log->add(Log::Dispatch::Message::Passing->new(
+ name => 'myapp_aggregate_log',
+ min_level => 'debug',
+ output => Message::Passing::Filter::Encode::JSON->new(
+ output_to => Message::Passing::Output::ZeroMQ->new(
+ connect => 'tcp://192.168.0.1:5558',
+ )
+ ),
+ ));
+
+ $log->warn($_) for qw/ foo bar baz /;
On your log aggregation server, just run the message-passing utility:
message-passing --input ZeroMQ --input_options '{"socket_bind":"tcp://*:5222"}' \
--output File --output_options '{"filename":"/tmp/my_test.log"}'
-CONNECTION DIRECTION
- Note that in ZeroMQ, the connection direction and the direction of
- message flow can be entirely opposite. I.e. a client can connect to a
- server and send messages to it, or receive messages from it (depending
- on the direction of the socket types).
-
SOCKET TYPES
ZeroMQ supports multiple socket types, the only ones used in
Message::Passing::ZeroMQ are:
@@ -73,6 +84,33 @@ SOCKET TYPES
In Message::Passing terms, Message::Passing::Input::ZeroMQ is for PULL
sockets, and Message::Passing::Output::ZeroMQ is for PUSH sockets.
+CONNECTION DIRECTION
+ Note that in ZeroMQ, the connection direction and the direction of
+ message flow can be entirely opposite. I.e. a client can connect to a
+ server and send messages to it, or receive messages from it (depending
+ on the direction of the socket types).
+
+CONNECTION ATTRIBUTES
+ Both Message::Passing::Input::ZeroMQ and
+ Message::Passing::Output::ZeroMQ support either binding a server or
+ connecting to a remote host, due to the fact that ZeroMQ connections can
+ be in any direction, as noted above.
+
+ Therefore, each input or output should have one (but not both!) of the
+ following attributes:
+
+ connect
+ Connects to a remote server, e.g. "tcp://192.168.0.1:5222"
+
+ socket_bind
+ Binds a server and waits for connections from clients, e.g.
+ "tcp://*:5222"
+
+ socket_type
+ This defaults to "SUB" for Message::Passing::Input::ZeroMQ and "PUB" for
+ Message::Passing::Output::ZeroMQ, however you can override it to
+ "PUSH"/"PULL" as appropriate for your use case if desired.
+
MORE COMPLEX EXAMPLES
With this in mind, we can easily create a system which aggregates
messages from multiple publishers, and passes them out (in a round-robin
@@ -115,6 +153,7 @@ SEE ALSO
Message::Passing
ZeroMQ
<http://www.zeromq.org/>
+ <http://zguide.zeromq.org/page:all>
AUTHOR
Tomas (t0m) Doran <bobtfish at bobtfish.net>
diff --git a/lib/Message/Passing/Input/ZeroMQ.pm b/lib/Message/Passing/Input/ZeroMQ.pm
index efb4e51..bc96287 100644
--- a/lib/Message/Passing/Input/ZeroMQ.pm
+++ b/lib/Message/Passing/Input/ZeroMQ.pm
@@ -74,8 +74,21 @@ sub BUILD {
Message::Passing::Input::ZeroMQ - input messages from ZeroMQ.
+=head1 SYNOPSIS
+
+ message-passing --output STDOUT --input ZeroMQ --input_options '{"socket_bind":"tcp://*:5552"}'
+
=head1 DESCRIPTION
+A L<Message::Passing> ZeroMQ input class.
+
+Can be used as part of a chain of classes with the L<message-passing> utility, or directly as
+an input with L<Message::Passing::DSL>.
+
+=head1 ATTRIBUTES
+
+See L<Message::Passing::ZeroMQ/CONNECTION ATTRIBUTES>
+
=head1 SEE ALSO
=over
diff --git a/lib/Message/Passing/Output/ZeroMQ.pm b/lib/Message/Passing/Output/ZeroMQ.pm
index 286d428..5e22eb7 100644
--- a/lib/Message/Passing/Output/ZeroMQ.pm
+++ b/lib/Message/Passing/Output/ZeroMQ.pm
@@ -43,21 +43,28 @@ Message::Passing::Output::ZeroMQ - output messages to ZeroMQ.
# simple logging.
# Or use directly on command line:
- message-passing --input STDIN --output ZeroMQ
+ message-passing --input STDIN --output ZeroMQ --output_options \
+ '{"connect":"tcp://192.168.0.1:5552"}'
{"data":{"some":"data"},"@metadata":"value"}
=head1 DESCRIPTION
-A L<Message::Passing> L<ZeroMQ> output class.
+A L<Message::Passing> ZeroMQ output class.
Can be used as part of a chain of classes with the L<message-passing> utility, or directly as
a logger in normal perl applications.
+=head1 ATTRIBUTES
+
+See L<Message::Passing::ZeroMQ/CONNECTION ATTRIBUTES>.
+
=head1 METHODS
-=head2 consume
+=head2 consume ($msg)
-Sends a message.
+Sends a message, as-is. This means that you must have encoded the message to a string before
+sending it. The C<message-pass> utility will do this for you into JSON, or you can
+do it manually as shown in the example in L<Message::Passing::ZeroMQ>.
=head1 SEE ALSO
diff --git a/lib/Message/Passing/ZeroMQ.pm b/lib/Message/Passing/ZeroMQ.pm
index e641e3d..e8bfa6c 100644
--- a/lib/Message/Passing/ZeroMQ.pm
+++ b/lib/Message/Passing/ZeroMQ.pm
@@ -26,11 +26,11 @@ Message::Passing::ZeroMQ - input and output messages to ZeroMQ.
=head1 SYNOPSIS
# Terminal 1:
- $ message-passing --input STDIN --output ZeroMQ --output_options '{"connect":"tcp://127.0.0.1:5558"}'
+ $ message-passing --input STDIN --output ZeroMQ --output_options '{"connect":"tcp://127.0.0.1:5552"}'
{"data":{"some":"data"},"@metadata":"value"}
# Terminal 2:
- $ message-passing --output STDOUT --input ZeroMQ --input_options '{"socket_bind":"tcp://*:5558"}'
+ $ message-passing --output STDOUT --input ZeroMQ --input_options '{"socket_bind":"tcp://*:5552"}'
{"data":{"some":"data"},"@metadata":"value"}
=head1 DESCRIPTION
@@ -54,22 +54,33 @@ server) is significantly less acceptable than the loss of non-essential logging
=head1 HOW TO USE
-In your application emitting messages, you can either use L<Message::Passing::Output::ZeroMQ> directly, of you can use
-it via L<Log::Dispatch::Message::Passing>.
+In your application emitting messages, you can either use L<Message::Passing::Output::ZeroMQ> directly,
+or you can use it via L<Log::Dispatch::Message::Passing>.
- # FIXME - Example code, including overriding IP to connect to here
+ use Log::Dispatch;
+ use Log::Dispatch::Message::Passing;
+ use Message::Passing::Output::ZeroMQ;
+ use Message::Passing::Filter::Encode::JSON;
+
+ my $log = Log::Dispatch->new;
+
+ $log->add(Log::Dispatch::Message::Passing->new(
+ name => 'myapp_aggregate_log',
+ min_level => 'debug',
+ output => Message::Passing::Filter::Encode::JSON->new(
+ output_to => Message::Passing::Output::ZeroMQ->new(
+ connect => 'tcp://192.168.0.1:5558',
+ )
+ ),
+ ));
+
+ $log->warn($_) for qw/ foo bar baz /;
On your log aggregation server, just run the message-passing utility:
message-passing --input ZeroMQ --input_options '{"socket_bind":"tcp://*:5222"}' \
--output File --output_options '{"filename":"/tmp/my_test.log"}'
-=head1 CONNECTION DIRECTION
-
-Note that in ZeroMQ, the connection direction and the direction of message flow can be
-entirely opposite. I.e. a client can connect to a server and send messages to it, or
-receive messages from it (depending on the direction of the socket types).
-
=head1 SOCKET TYPES
ZeroMQ supports multiple socket types, the only ones used in Message::Passing::ZeroMQ are:
@@ -93,6 +104,34 @@ a number of connecting clients (PULL)
In Message::Passing terms, L<Message::Passing::Input::ZeroMQ> is for PULL sockets, and
L<Message::Passing::Output::ZeroMQ> is for PUSH sockets.
+=head1 CONNECTION DIRECTION
+
+Note that in ZeroMQ, the connection direction and the direction of message flow can be
+entirely opposite. I.e. a client can connect to a server and send messages to it, or
+receive messages from it (depending on the direction of the socket types).
+
+=head1 CONNECTION ATTRIBUTES
+
+Both L<Message::Passing::Input::ZeroMQ> and L<Message::Passing::Output::ZeroMQ> support
+either binding a server or connecting to a remote host, due to the fact that ZeroMQ connections
+can be in any direction, as noted above.
+
+Therefore, each input or output should have one (but not both!) of the following attributes:
+
+=head2 connect
+
+Connects to a remote server, e.g. C<< tcp://192.168.0.1:5222 >>
+
+=head2 socket_bind
+
+Binds a server and waits for connections from clients, e.g. C<< tcp://*:5222 >>
+
+=head2 socket_type
+
+This defaults to C<SUB> for L<Message::Passing::Input::ZeroMQ> and C<PUB> for
+L<Message::Passing::Output::ZeroMQ>, however you can override it to C<PUSH>/C<PULL> as
+appropriate for your use case if desired.
+
=head1 MORE COMPLEX EXAMPLES
With this in mind, we can easily create a system which aggregates messages from
@@ -142,6 +181,8 @@ For more detailed information about ZeroMQ and how it works, please consult the
=item L<http://www.zeromq.org/>
+=item L<http://zguide.zeromq.org/page:all>
+
=back
=head1 AUTHOR
--
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/pkg-perl/packages/libmessage-passing-zeromq-perl.git
More information about the Pkg-perl-cvs-commits
mailing list