Package org.zeromq

Class ZActor

  • All Implemented Interfaces:
    ZAgent

    public class ZActor
    extends ZStar

    First implementation of a background actor remotely controlled for ØMQ.

    This implementation is based on the ZStar one (TODO via inheritance now but this is not totally stamped and the use of the ZAgent would probably limit the collateral damages if changed) so you should be first familiar with the metaphor there.

    To extensively sum up:
    A side or endpoint designates the same thing: the thread where lives one of the two parts of the Actor system.

    An actor has 2 sides (with a trial to use theater terms for fun (: and hopefully clarity :)
    • the Corbeille side, or control side
      This is where one can send and receive control messages to the underneath actor via the ZActor and/or its agent.
      The ZActor lives on this side and is a way to safely communicate with the distant provided Actor
      Note: Corbeille is a french word designing the most privileged seats in the theater, 1st floor, just above the orchestra (Wikipedia...). It was the place where the King was standing during the shows, with the best seat of course! Fast users who would want to communicate with the distant ZActor.Actor can use ZStar.send(ZMsg) or ZStar.recv() from the ZActor as the ZActor is itself an agent!
    • the Plateau side, or background side where all the performances are made by the provided actor.
      The provided ZActor.Actor is living on the Plateau.
      The Plateau is made of the Stage where the effective processing occurs and of the Backstage where the provided actor can send and receive control messages to and from the ZActor.
      From this side, the work is done via callbacks using the template-method pattern, applied with interfaces (?)

    The main purpose (or at least its intent) of this class is to clarify the contracts, roles, responsibilities and action levers related to the Plateau.
    The provided Actor will not be alone to do the processing of each loop.
    It will be helped by a double responsible for passing the appropriate structures at the right moment. As a developer point of view, this double helps also to limit the complexity of the process. However Double is an uncommon one, capturing all the lights while letting the Actor taking care of all the invisible work in the shadows. And this is one of the points where we begin to reach the limits of the metaphor...
    The ZActor takes care of the establishment of the background processing, calling the provided Actor at appropriate times via its Double. It can also manage the exited state on the control side, if using the provided ZStar.send(ZMsg) or ZStar.recv() methods.
    It also takes care of the automatic closing of sockets and context if it had to create one.
    An actor is basically a contract interface that anyone who uses this ZActor SHALL comply to.

    TODO This interface is still a little bit tough, as instead of the 5+2 Star callbacks, here are 10! But they allow you to have a hand on the key points of the looping, restart a new actor if needed, ... Anyway, adapters like a simple one or a duo are present to help you on that, reducing the amount of methods to write.

    PS: Je sais qu'il y a une différence entre acteur et comédien :)

    PPS: I know nothing about theater!

    Example of code for a minimalistic actor with no socket handling other than the control pipe:

     
            Actor acting = new ZActor.SimpleActor()
            {
                public List<Socket> createSockets(ZContext ctx, Object ... args)
                {
                    assert ("TEST".equals(args[0]));
                    return Arrays.asList(ctx.createSocket(ZMQ.PUB));
                }
    
                public boolean backstage(Socket pipe, ZPoller poller, int events)
                {
                    String cmd = pipe.recvStr();
                    if ("HELLO".equals(cmd)) {
                        pipe.send("WORLD");
                        // end of the actor
                        return false;
                    }
                    return true;
                }
            };
            ZActor actor = new ZActor(acting, "LOCK", Arrays.asList("TEST").toArray());
            Socket pipe = actor.pipe();
            boolean rc = pipe.send("HELLO");
            assert (rc);
            ZMsg msg = actor.recv();
            String world = msg.popString();
            assert ("WORLD".equals(world));
            msg = actor.recv();
            assert (msg == null);
            rc = actor.sign();
            assert (!rc);
            rc = actor.send("whatever");
            assert (!rc);
            // don't try to use the pipe
    
    • Constructor Detail

      • ZActor

        public ZActor​(ZActor.Actor actor,
                      java.lang.String motdelafin,
                      java.lang.Object... args)
        Creates a new ZActor. A new context will be created and closed at the stop of the operation.
        Parameters:
        actor - the actor handling messages from either stage and backstage
        motdelafin - the final word used to mark the end of the actor. Null to disable this mechanism.
        args - the optional arguments that will be passed to the distant actor
      • ZActor

        @Deprecated
        public ZActor​(ZAgent.SelectorCreator selector,
                      ZActor.Actor actor,
                      java.lang.String motdelafin,
                      java.lang.Object... args)
        Creates a new ZActor.
        Parameters:
        selector - the creator of the selector used on the Plateau.
        actor - the actor handling messages from either stage and backstage
        motdelafin - the final word used to mark the end of the actor. Null to disable this mechanism.
        args - the optional arguments that will be passed to the distant actor
      • ZActor

        @Deprecated
        public ZActor​(ZContext context,
                      ZAgent.SelectorCreator selector,
                      ZActor.Actor actor,
                      java.lang.String motdelafin,
                      java.lang.Object... args)
        Creates a new ZActor.
        Parameters:
        context - the main context used. If null, a new context will be created and closed at the stop of the operation. If not null, it is the responsibility of the caller to close it.
        selector - the creator of the selector used on the Plateau.
        actor - the actor handling messages from either stage and backstage
        motdelafin - the final word used to mark the end of the actor. Null to disable this mechanism.
        args - the optional arguments that will be passed to the distant actor
      • ZActor

        public ZActor​(ZContext context,
                      ZActor.Actor actor,
                      java.lang.String motdelafin,
                      java.lang.Object... args)
        Creates a new ZActor.
        Parameters:
        context - the main context used. If null, a new context will be created and closed at the stop of the operation. If not null, it is the responsibility of the caller to close it.
        actor - the actor handling messages from either stage and backstage
        motdelafin - the final word used to mark the end of the actor. Null to disable this mechanism.
        args - the optional arguments that will be passed to the distant actor