mlm_server(3)
=============

NAME
----
mlm_server - Malamute Server

SYNOPSIS
--------
----
//  To work with mlm_server, use the CZMQ zactor API:
//
//  Create new mlm_server instance, passing logging prefix:
//
//      zactor_t *mlm_server = zactor_new (mlm_server, "myname");
//  
//  Destroy mlm_server instance
//
//      zactor_destroy (&mlm_server);
//  
//  Enable verbose logging of commands and activity:
//
//      zstr_send (mlm_server, "VERBOSE");
//
//  Bind mlm_server to specified endpoint. TCP endpoints may specify
//  the port number as "*" to aquire an ephemeral port:
//
//      zstr_sendx (mlm_server, "BIND", endpoint, NULL);
//
//  Return assigned port number, specifically when BIND was done using an
//  an ephemeral port:
//
//      zstr_sendx (mlm_server, "PORT", NULL);
//      char *command, *port_str;
//      zstr_recvx (mlm_server, &command, &port_str, NULL);
//      assert (streq (command, "PORT"));
//
//  Specify configuration file to load, overwriting any previous loaded
//  configuration file or options:
//
//      zstr_sendx (mlm_server, "LOAD", filename, NULL);
//
//  Set configuration path value:
//
//      zstr_sendx (mlm_server, "SET", path, value, NULL);
//    
//  Save configuration data to config file on disk:
//
//      zstr_sendx (mlm_server, "SAVE", filename, NULL);
//
//  Send zmsg_t instance to mlm_server:
//
//      zactor_send (mlm_server, &msg);
//
//  Receive zmsg_t instance from mlm_server:
//
//      zmsg_t *msg = zactor_recv (mlm_server);
//
//  This is the mlm_server constructor as a zactor_fn:
//
MLM_EXPORT void
    mlm_server (zsock_t *pipe, void *args);

//  Self test of this class
MLM_EXPORT void
    mlm_server_test (bool verbose);
----

DESCRIPTION
-----------

This actor implements the Malamute service. The actor uses the CZMQ socket
command interface, rather than a classic C API. You can start as many
instances of the Malamute service as you like. Each will run in its own
namespace, as virtual hosts. This class is wrapped as a main program via
the malamute.c application, and can be wrapped in other languages in the
same way as any C API.

This is a minimal, incomplete implementation of Malamute. It does however
not have any known bugs.

EXAMPLE
-------
.From mlm_server_test method
----
zactor_t *server = zactor_new (mlm_server, "mlm_server_test");
if (verbose)
    zstr_send (server, "VERBOSE");
zstr_sendx (server, "BIND", "ipc://@/malamute", NULL);

zsock_t *reader = zsock_new (ZMQ_DEALER);
assert (reader);
zsock_connect (reader, "ipc://@/malamute");
zsock_set_rcvtimeo (reader, 500);

mlm_proto_t *proto = mlm_proto_new ();

//  Server insists that connection starts properly
mlm_proto_set_id (proto, MLM_PROTO_STREAM_WRITE);
mlm_proto_send (proto, reader);
mlm_proto_recv (proto, reader);
assert (mlm_proto_id (proto) == MLM_PROTO_ERROR);
assert (mlm_proto_status_code (proto) == MLM_PROTO_COMMAND_INVALID);

//  Now do a stream publish-subscribe test
zsock_t *writer = zsock_new (ZMQ_DEALER);
assert (writer);
zsock_connect (writer, "ipc://@/malamute");
zsock_set_rcvtimeo (reader, 500);

//  Open connections from both reader and writer
mlm_proto_set_id (proto, MLM_PROTO_CONNECTION_OPEN);
mlm_proto_send (proto, reader);
mlm_proto_recv (proto, reader);
assert (mlm_proto_id (proto) == MLM_PROTO_OK);

mlm_proto_set_id (proto, MLM_PROTO_CONNECTION_OPEN);
mlm_proto_send (proto, writer);
mlm_proto_recv (proto, writer);
assert (mlm_proto_id (proto) == MLM_PROTO_OK);

//  Prepare to write and read a "weather" stream
mlm_proto_set_id (proto, MLM_PROTO_STREAM_WRITE);
mlm_proto_set_stream (proto, "weather");
mlm_proto_send (proto, writer);
mlm_proto_recv (proto, writer);
assert (mlm_proto_id (proto) == MLM_PROTO_OK);

mlm_proto_set_id (proto, MLM_PROTO_STREAM_READ);
mlm_proto_set_pattern (proto, "temp.*");
mlm_proto_send (proto, reader);
mlm_proto_recv (proto, reader);
assert (mlm_proto_id (proto) == MLM_PROTO_OK);

//  Now send some weather data, with null contents
mlm_proto_set_id (proto, MLM_PROTO_STREAM_SEND);
mlm_proto_set_subject (proto, "temp.moscow");
mlm_proto_send (proto, writer);
mlm_proto_set_subject (proto, "rain.moscow");
mlm_proto_send (proto, writer);
mlm_proto_set_subject (proto, "temp.chicago");
mlm_proto_send (proto, writer);
mlm_proto_set_subject (proto, "rain.chicago");
mlm_proto_send (proto, writer);
mlm_proto_set_subject (proto, "temp.london");
mlm_proto_send (proto, writer);
mlm_proto_set_subject (proto, "rain.london");
mlm_proto_send (proto, writer);

//  We should receive exactly three deliveries, in order
mlm_proto_recv (proto, reader);
assert (mlm_proto_id (proto) == MLM_PROTO_STREAM_DELIVER);
assert (streq (mlm_proto_subject (proto), "temp.moscow"));

mlm_proto_recv (proto, reader);
assert (mlm_proto_id (proto) == MLM_PROTO_STREAM_DELIVER);
assert (streq (mlm_proto_subject (proto), "temp.chicago"));

mlm_proto_recv (proto, reader);
assert (mlm_proto_id (proto) == MLM_PROTO_STREAM_DELIVER);
assert (streq (mlm_proto_subject (proto), "temp.london"));

mlm_proto_destroy (&proto);
    
//  Finished, we can clean up
zsock_destroy (&writer);
zsock_destroy (&reader);
zactor_destroy (&server);

----