NAME

ZMQ::Declare::DSL - DSL for declaring 0MQ infrastructure

SYNOPSIS

  use ZMQ::Declare::DSL;
  
  my $zdcf = declare_zdcf {
  
      app {
          name 'weather';
  
          context { iothreads 1 };
  
          device {
              name 'client';
              sock {
                  name 'weather_stream';
                  type 'sub';
                  conn qw(tcp://localhost:12345);
                  option subscribe => "70123"; # ZIP code in this example
              };
          };
  
          device {
              name 'server';
              sock {
                  name 'weather_publisher';
                  type 'pub';
                  bnd qw(tcp://*:12345);
              };
          };
      };
  
  };
  
  # elsewhere
  my $server = $zdcf->application("weather")->device('server');
  $server->implementation(sub {
    my ($runtime) = @_;
    # server main loop here
    return();
  });
  $server->run();
  
  # yet elsewhere
  my $client = $zdcf->application("weather")->device('client');
  $client->implementation(sub {
    my ($runtime) = @_;
    # client main loop here
    return();
  });
  $client->run();

DESCRIPTION

This is experimental software. Interfaces and implementation are subject to change. If you are interested in using this in production, please get in touch to gauge the current state of stability.

This module defines a domain specific language (which just so happens to be valid Perl that's slightly beaten into shape) for declaring 0MQ infrastructure. Please read ZMQ::Declare before you proceed with this document.

This module is just a thin syntax-sugar layer on top of simply creating a regular nested Perl data structure and passing it to ZMQ::Declare::ZDCF-new()>. It adds no features beyond a different syntax. Unless you find the syntax very attractive, consider using a simpler way to declare 0MQ infrastructure.

Generally speaking, there are multiple kinds of functions in this module: There are those that have a notion of scope, such as the outer declare_zdcf BLOCK and app BLOCK, context BLOCK, device BLOCK, and socket BLOCK. And there are those that simply set a property of the enclosing object (well, scope): name STRING, type STRING, bnd LIST, conn LIST, option LIST, and iothreads INTEGER.

Most of these can only occurr within certain scopes. For example, iothreads can only be set within a context and a context can only appear within an app, but a name is valid in an app, a device, or a socket. Etc.

EXPORTS

This module exports a plethora of functions (as of this writing, all functions that are documented below) by default. That's the point.

FUNCTIONS

declare_zdcf

The outermost function that starts the declaration of a new ZDCF specification containing zero or more apps.

app

Defines a new app within a ZDCF specification. Only valid within the outermost declare_zdcf block. Must cointain at least a name property.

Can contain one or more devices.

context

Defines a threading context of an app. Can occur zero or one time per app, but cannot be used outside an app or inside its substructures (like devices).

iothreads

Defines the number of iothreads in a threading context. Defaults to one. This is the only property that is currently valid in a context.

device

Defines a single device within an app. Can occur zero or more times in each app. Not valid outside of an app definition or within its substructures.

Can contain zero or more sockets. May have a type and a name property. The name defaults to the app name, but that requires that the app name declaration appears before the device declaration.

sock

Defines a single socket within a device. Can occur zero or more times in each device. Not valid outside of a device definition or within its substructures.

Requires at least a name and a type property and at least one bind or connect property.

name

Defines the name of the enclosing object. Valid for apps, devices, and sockets.

type

Defines the type of the enclosing object. Valid for devices and sockets.

bnd

Given a list of endpoints (strings), adds to the set of endpoints that the enclosing socket is to bind to.

Valid any number of times within a socket. Either bnd or conn need to appear at least once in a socket.

conn

Same as bnd, but for connecting to sockets instead of binding.

option

Given a list of key/value pairs, sets socket options. Valid any number of times within a socket.

SEE ALSO

ZMQ::Declare

ZeroMQ

AUTHOR

Steffen Mueller <smueller@cpan.org>

COPYRIGHT AND LICENSE

Copyright (C) 2012 by Steffen Mueller

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.1 or, at your option, any later version of Perl 5 you may have available.

cpanm ZMQ::Declare

perl -MCPAN -e shell
install ZMQ::Declare