Difference between revisions of "Zeromq package"

From Octave
Jump to navigation Jump to search
 
(10 intermediate revisions by 3 users not shown)
Line 5: Line 5:
 
== package requirements ==
 
== package requirements ==
  
The {{Forge|zeromq}} package requires the zeromq libraries and include files to be installed in order to compile.
+
The {{Forge|zeromq}} package requires the [http://zeromq.org/ ZeroMQ] libraries and include files to be installed in order to compile.
  
 
for fedora: yum install zeromq-devel
 
for fedora: yum install zeromq-devel
Line 13: Line 13:
 
== octave installation ==
 
== octave installation ==
  
With the ZeroMQ library installed, from octave commmand line:
+
With the [http://zeromq.org/ ZeroMQ] library installed, from octave commmand line:
  
 
  >> pkg install -forge zeromq
 
  >> pkg install -forge zeromq
Line 23: Line 23:
 
  >> pkg load zeromq
 
  >> pkg load zeromq
  
 +
Look at the quick reference for the package:
  
 +
  >> help zeromq
  
[[Category:Octave-Forge]]
+
== Differences between C and Octave bindings ==
 +
 
 +
The Octave binding is a subset of the C binding of the ZeroMQ library.
 +
 
 +
Major differences are:
 +
 
 +
1. The octave binding creates a single zeromq context that is used for all zeromq sockets. In the C bindings, the programmer must create a context and use it during socket creation.
 +
 
 +
2. only limited zmq_getsockopt and zmq_setsockopt is currently implemented.
 +
 
 +
3. functions mostly return true or false for whether they succeeded or failed. In the C binding, 0 signified success.
 +
 
 +
== The functions ==
 +
 
 +
iszmq
 +
          Determine whether H is a zeromq socket object.
 +
 
 +
zmq_bind
 +
          Bind a zeromq socket to a endpoint.
 +
 
 +
zmq_close
 +
          Close a zeromq socket.
 +
 
 +
zmq_connect
 +
          Connect a zeromq socket to a endpoint
 +
 
 +
zmq_curve_keypair
 +
          Generate a random private/public keypair
 +
 
 +
zmq_curve_public
 +
          Derive the public key from a private key
 +
 
 +
zmq_disconnect
 +
          Disconnect a zeromq socket from an endpoint.
 +
 
 +
zmq_errno
 +
          Get system errno value.
 +
 
 +
zmq_getsockopt
 +
          Get current value of a zeromq socket option.
 +
 
 +
zmq_has
 +
          Check if the zmq library supports a given feature.
 +
 
 +
zmq_poll
 +
          Poll a socket or sockets for a timeout or incoming data
 +
          available.
 +
 
 +
zmq_recv
 +
          Attempt to read data from a zeromq socket.
 +
 
 +
zmq_send
 +
          Attempt to send data from a zeromq socket.
 +
 
 +
zmq_setsockopt
 +
          Set a zeromq socket option.
 +
 
 +
zmq_socket
 +
          Create a zeromq socket.
 +
 
 +
zmq_strerror
 +
          Get the last zmq error string.
 +
 
 +
zmq_unbind
 +
          Unbind a previously bound zeromq socket.
 +
 
 +
zmq_version
 +
          Get the zeromq library version numbers.
 +
 
 +
zmq_z85_decode
 +
          Decode a z85 encoded string to a binary key.
 +
 
 +
zmq_z85_encode
 +
          Encode a binary key as Z85 printable text.
 +
 
 +
= Examples =
 +
 
 +
The zeromq package comes with a number of examples included in it. They can be opened in octave using:
 +
 
 +
  >> edit examples/zmq_example1.m
 +
 
 +
 
 +
== basic request/reply pattern ==
 +
 
 +
Example based on client/server example from [http://zguide.zeromq.org/page:all#Ask-and-Ye-Shall-Receive http://zguide.zeromq.org/page:all#Ask-and-Ye-Shall-Receive]
 +
 
 +
The client sends a "Hello" to the server which responds back "World". No error checking or data validation is done in the example.
 +
 
 +
{{Code|Server code|<syntaxhighlight lang="octave" style="font-size:13px">
 +
% zeromq package must be installed and loaded to work
 +
pkg load zeromq
 +
 
 +
% dont buffer output
 +
more off
 +
 
 +
printf ("Creating hello world server...\n");
 +
 
 +
% create reply socket, and bind it to port 5555
 +
sock = zmq_socket (ZMQ_REP);
 +
 
 +
zmq_bind (sock, "tcp://*:5555");
 +
 
 +
printf ("Waiting for clients ...\n");
 +
 
 +
% loop forever, waiting for client requests and responding back 
 +
while (true)
 +
  recievedata = zmq_recv (sock, 10, 0);
 +
  printf ("Received Hello\n");
 +
  zmq_send (sock, "World", 5, 0);
 +
endwhile
 +
</syntaxhighlight>}}
 +
 
 +
{{Code|Client code|<syntaxhighlight lang="octave" style="font-size:13px">
 +
% zeromq package must be installed and loaded to work
 +
pkg load zeromq
 +
 
 +
% dont buffer output
 +
more off
 +
 
 +
printf ("Connecting to hello world server...\n");
 +
 
 +
 
 +
% Create socket and connect to server
 +
 
 +
sock = zmq_socket (ZMQ_REQ);
 +
zmq_connect (sock, "tcp://localhost:5555");
 +
 
 +
for request_nbr = [1:10]
 +
  printf ("Sending Hello %d...\n", request_nbr);
 +
 
 +
  zmq_send (sock, uint8("Hello"), 5, 0);
 +
 
 +
  % try to read up to 10 bytes of reply data.
 +
  printf ("Waiting for server response %d... (Ctrl-C to exit)\n", request_nbr);
 +
 
 +
  recieved = zmq_recv (sock, 10, 0);
 +
  printf ("Received World %d\n", request_nbr);
 +
endfor
 +
   
 +
zmq_close (sock);
 +
</syntaxhighlight>}}
 +
 
 +
== basic publish/subscribe pattern ==
 +
 
 +
Example based on client/server example from [http://zguide.zeromq.org/page:all#Getting-the-Message-Out http://zguide.zeromq.org/page:all#Getting-the-Message-Out]
 +
 
 +
The server pushes 'weather updates' for random zipcodes. The client subscribes to the server just for zipcode 10001.
 +
 
 +
{{Code|Server code|<syntaxhighlight lang="octave" style="font-size:13px">
 +
% zeromq package must be installed and loaded to work
 +
pkg load zeromq
 +
 
 +
% dont buffer output
 +
more off
 +
 
 +
publisher = zmq_socket (ZMQ_PUB);
 +
 
 +
rc = zmq_bind (publisher, "tcp://*:5556");
 +
assert (rc);
 +
 
 +
while (true)
 +
  %  Get values that will fool the boss
 +
  zipcode    = 10000 + randi (20);
 +
  temperature = randi (215) - 80;
 +
  relhumidity = randi (50) + 10;
 +
 
 +
  %  Send message to all subscribers
 +
  update = sprintf ("%05d %d %d", zipcode, temperature, relhumidity);
 +
 
 +
  zmq_send (publisher, update);
 +
endwhile
 +
 
 +
zmq_close (publisher);
 +
</syntaxhighlight>}}
 +
 
 +
{{Code|Client code|<syntaxhighlight lang="octave" style="font-size:13px">
 +
% zeromq package must be installed and loaded to work
 +
pkg load zeromq
 +
 
 +
% dont buffer output
 +
more off
 +
 
 +
subscriber = zmq_socket (ZMQ_SUB);
 +
rc = zmq_connect (subscriber, "tcp://localhost:5556");
 +
assert (rc);
 +
 
 +
%  Subscribe to zipcode, default is NYC, 10001
 +
zipfilter = "10001 ";
 +
rc = zmq_setsockopt (subscriber, ZMQ_SUBSCRIBE, zipfilter);
 +
assert (rc);
 +
 
 +
%  Process 100 updates
 +
update_nbr = 0;
 +
total_temp = 0;
 +
 
 +
for update_nbr = 1:100
 +
  string = char( zmq_recv(subscriber, 128) );
 +
 
 +
  [zipcode, temperature, relhumidity, count, errmsg] = sscanf (string, "%d %d %d", "C");
 +
 
 +
  fprintf ("recieved a temp for zipcode '%s' of %dF\n", ...
 +
    zipfilter, temperature);
 +
 
 +
  total_temp += temperature;
 +
endfor
 +
 
 +
fprintf ("Average temperature for zipcode '%s' was %dF\n", ...
 +
  zipfilter, (total_temp / update_nbr));
 +
 
 +
zmq_close (subscriber);
 +
</syntaxhighlight>}}
 +
 
 +
 
 +
[[Category:Octave Forge]]

Latest revision as of 11:25, 6 August 2019

The zeromq package is part of the Octave Forge project and provides Octave bindings to the ZeroMQ library.

Installation[edit]

package requirements[edit]

The zeromq package requires the ZeroMQ libraries and include files to be installed in order to compile.

for fedora: yum install zeromq-devel

for ubuntu: apt install libzmq-dev

octave installation[edit]

With the ZeroMQ library installed, from octave commmand line:

>> pkg install -forge zeromq

Using it[edit]

Load it before any usage:

>> pkg load zeromq

Look at the quick reference for the package:

 >> help zeromq

Differences between C and Octave bindings[edit]

The Octave binding is a subset of the C binding of the ZeroMQ library.

Major differences are:

1. The octave binding creates a single zeromq context that is used for all zeromq sockets. In the C bindings, the programmer must create a context and use it during socket creation.

2. only limited zmq_getsockopt and zmq_setsockopt is currently implemented.

3. functions mostly return true or false for whether they succeeded or failed. In the C binding, 0 signified success.

The functions[edit]

iszmq
         Determine whether H is a zeromq socket object.
zmq_bind
         Bind a zeromq socket to a endpoint.
zmq_close
         Close a zeromq socket.
zmq_connect
         Connect a zeromq socket to a endpoint
zmq_curve_keypair
         Generate a random private/public keypair
zmq_curve_public
         Derive the public key from a private key
zmq_disconnect
         Disconnect a zeromq socket from an endpoint.
zmq_errno
         Get system errno value.
zmq_getsockopt
         Get current value of a zeromq socket option.
zmq_has
         Check if the zmq library supports a given feature.
zmq_poll
         Poll a socket or sockets for a timeout or incoming data
         available.
zmq_recv
         Attempt to read data from a zeromq socket.
zmq_send
         Attempt to send data from a zeromq socket.
zmq_setsockopt
         Set a zeromq socket option.
zmq_socket
         Create a zeromq socket.
zmq_strerror
         Get the last zmq error string.
zmq_unbind
         Unbind a previously bound zeromq socket.
zmq_version
         Get the zeromq library version numbers.
zmq_z85_decode
         Decode a z85 encoded string to a binary key.
zmq_z85_encode
         Encode a binary key as Z85 printable text.

Examples[edit]

The zeromq package comes with a number of examples included in it. They can be opened in octave using:

 >> edit examples/zmq_example1.m


basic request/reply pattern[edit]

Example based on client/server example from http://zguide.zeromq.org/page:all#Ask-and-Ye-Shall-Receive

The client sends a "Hello" to the server which responds back "World". No error checking or data validation is done in the example.

Code: Server code
% zeromq package must be installed and loaded to work
pkg load zeromq

% dont buffer output
more off

printf ("Creating hello world server...\n");

% create reply socket, and bind it to port 5555
sock = zmq_socket (ZMQ_REP);

zmq_bind (sock, "tcp://*:5555");
  
printf ("Waiting for clients ...\n");
  
% loop forever, waiting for client requests and responding back  
while (true)
  recievedata = zmq_recv (sock, 10, 0);
  printf ("Received Hello\n");
  zmq_send (sock, "World", 5, 0);
endwhile
Code: Client code
% zeromq package must be installed and loaded to work
pkg load zeromq

% dont buffer output
more off

printf ("Connecting to hello world server...\n");


% Create socket and connect to server

sock = zmq_socket (ZMQ_REQ);
zmq_connect (sock, "tcp://localhost:5555");

for request_nbr = [1:10]
  printf ("Sending Hello %d...\n", request_nbr);

  zmq_send (sock, uint8("Hello"), 5, 0);
  
  % try to read up to 10 bytes of reply data.
  printf ("Waiting for server response %d... (Ctrl-C to exit)\n", request_nbr); 

  recieved = zmq_recv (sock, 10, 0);
  printf ("Received World %d\n", request_nbr);
endfor
    
zmq_close (sock);

basic publish/subscribe pattern[edit]

Example based on client/server example from http://zguide.zeromq.org/page:all#Getting-the-Message-Out

The server pushes 'weather updates' for random zipcodes. The client subscribes to the server just for zipcode 10001.

Code: Server code
% zeromq package must be installed and loaded to work
pkg load zeromq

% dont buffer output
more off

publisher = zmq_socket (ZMQ_PUB);

rc = zmq_bind (publisher, "tcp://*:5556");
assert (rc);

while (true) 
  %  Get values that will fool the boss
  zipcode     = 10000 + randi (20);
  temperature = randi (215) - 80;
  relhumidity = randi (50) + 10;

  %  Send message to all subscribers
  update = sprintf ("%05d %d %d", zipcode, temperature, relhumidity);
  
  zmq_send (publisher, update);
endwhile

zmq_close (publisher);
Code: Client code
% zeromq package must be installed and loaded to work
pkg load zeromq

% dont buffer output
more off

subscriber = zmq_socket (ZMQ_SUB);
rc = zmq_connect (subscriber, "tcp://localhost:5556");
assert (rc);

%  Subscribe to zipcode, default is NYC, 10001
zipfilter = "10001 ";
rc = zmq_setsockopt (subscriber, ZMQ_SUBSCRIBE, zipfilter);
assert (rc);

%  Process 100 updates
update_nbr = 0;
total_temp = 0;

for update_nbr = 1:100
  string = char( zmq_recv(subscriber, 128) );

  [zipcode, temperature, relhumidity, count, errmsg] = sscanf (string, "%d %d %d", "C");
  
  fprintf ("recieved a temp for zipcode '%s' of %dF\n", ...
     zipfilter, temperature);

  total_temp += temperature;
endfor

fprintf ("Average temperature for zipcode '%s' was %dF\n", ...
  zipfilter, (total_temp / update_nbr));

zmq_close (subscriber);