Package io.sisu.nng.aio

Class Context

  • All Implemented Interfaces:
    java.lang.AutoCloseable
    public class Context
extends java.lang.Object
implements java.lang.AutoCloseable
    Wrapper of an NNG context, allowing for multi-threaded use of individual Sockets. Unlike the native nng_context, the Java Context provides a built in event dispatcher for the common event types (data received, data sent, wake from sleep). While I'm still designing the high-level API around this, for now there are 3 potential approaches for using a Context: 1. Synchronously using sendMessageSync()/recvMessageSync 2. Asynchronously with CompletableFutures using sendMessage()/recvMessage() 3. Asynchronously with callbacks via (optionally) registering event handlers. In the 3rd case (event handlers), one must "set the wheels in motion" by performing an initial asynchronous operation (like via a recvMessage() call). NOTE: Given Contexts are primarily for asynchronous usage and don't require their own dedicated threads, it's important to keep the Context from being garbage collected.

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      static class  Context.Event
      The supported asynchronous event types, corresponding to the core asynchronous operations
      static class  Context.Work
      A unit of asynchronous work awaiting completion.

    • Constructor Summary

      Constructors 
      Constructor Description
      Context​(Socket socket)
      Create a new Context for the given Socket.

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void close()
      Close the Context and try to safely release any resources (e.g.
      java.util.concurrent.CompletableFuture<Message> receiveMessage()
      Receive a Message asynchronously on this Context.
      Message receiveMessageSync()
      Try to receive a Message on the Context, blocking until received.
      java.util.concurrent.CompletableFuture<java.lang.Void> sendMessage​(Message msg)
      Send a Message on the Context.
      void sendMessageSync​(Message msg)
      Attempt to send the given Message synchronously on the Context, blocking until it's either accepted for sending, an error occurs, or a timeout.
      void setReceiveTimeout​(int timeoutMillis)
      Set a receive timeout on the Context.
      void setRecvHandler​(java.util.function.BiConsumer<ContextProxy,​Message> handler)
      Set a receive event handler on the Context, replacing the existing if present.
      void setSendHandler​(java.util.function.Consumer<ContextProxy> handler)
      Set a send event handler on the Context, replacing the existing if present.
      void setSendTimeout​(int timeoutMillis)
      Set a send timeout on the Context
      void setWakeHandler​(java.util.function.Consumer<ContextProxy> handler)
      Set a wake event handler on the Context, replacing the existing if present.
      java.util.concurrent.CompletableFuture<java.lang.Void> sleep​(int millis)
      Sleep the Context for the given duration, triggering the Wake handler upon timeout.

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Constructor Detail

      • Context

        public Context​(Socket socket)
        throws NngException
        Create a new Context for the given Socket. Note: Not all protocols support Contexts (e.g. Push0/Pull0)
        Parameters:
        socket - the given Socket to create a new Context for
        Throws:
        NngException - on an nng error

    • Method Detail

      • setRecvHandler

        public void setRecvHandler​(java.util.function.BiConsumer<ContextProxy,​Message> handler)
        Set a receive event handler on the Context, replacing the existing if present. It will be called upon completion of a Receive event regardless of outcome. The handler is of the form BiConsumer<Contextproxy, Message> and will have a reference to this Context's ContextProxy set as well as a reference the received Message instance. Note: For now, with the current API, it's advised that the handler free the Message itself if it's not using it for a send operation or storing it for later use.
        Parameters:
        handler - the receive event handler

      • setSendHandler

        public void setSendHandler​(java.util.function.Consumer<ContextProxy> handler)
        Set a send event handler on the Context, replacing the existing if present. It will be called upon completion of a Send event regardless of outcome. The send handler will be provided a reference to a ContextProxy, corresponding to this Context, when called. The handler should interact with the Context using the proxy and not via a captured reference to the Context.
        Parameters:
        handler - the send handler to set

      • setWakeHandler

        public void setWakeHandler​(java.util.function.Consumer<ContextProxy> handler)
        Set a wake event handler on the Context, replacing the existing if present. It will be called on completion of a sleep event, regardless of outcome. The wake handler will be provided a reference to a ContextProxy, corresponding to this Context, when called. The handler should interact with the Context using the proxy and not via a captured reference to the Context.
        Parameters:
        handler - the send handler to set

      • close

        public void close()
           throws NngException
        Close the Context and try to safely release any resources (e.g. the Aio) in advance of garbage collection.
        Specified by:
        close in interface java.lang.AutoCloseable
        Throws:
        NngException - on error closing the Context

      • receiveMessage

        public java.util.concurrent.CompletableFuture<Message> receiveMessage()
        Receive a Message asynchronously on this Context. The Message is owned by the JVM and caller and should be either used for a subsequent send operation or freed when no longer required.
        Returns:
        a CompletableFuture that is fulfilled with the Message upon success, or completed exceptionally on failure or error.

      • receiveMessageSync

        public Message receiveMessageSync()
                           throws NngException
        Try to receive a Message on the Context, blocking until received.
        Returns:
        the received Message
        Throws:
        NngException - on error or timeout

      • sendMessage

        public java.util.concurrent.CompletableFuture<java.lang.Void> sendMessage​(Message msg)
        Send a Message on the Context. If the Message is accepted for sending, the Message will be invalidated.
        Parameters:
        msg - the Message to send
        Returns:
        a CompletableFuture that will either complete on success or complete exceptionally on error or timeout. It's the caller's responsibility to then either retry or free the Message.

      • sendMessageSync

        public void sendMessageSync​(Message msg)
                     throws NngException
        Attempt to send the given Message synchronously on the Context, blocking until it's either accepted for sending, an error occurs, or a timeout. If the Message is accepted for sending, it will be marked invalid for future use.
        Parameters:
        msg - the Message to send
        Throws:
        NngException - on error or timeout

      • sleep

        public java.util.concurrent.CompletableFuture<java.lang.Void> sleep​(int millis)
        Sleep the Context for the given duration, triggering the Wake handler upon timeout.
        Parameters:
        millis - number of milliseconds to sleep
        Returns:
        a CompletableFuture that completes upon the wake event concluding or an error

      • setReceiveTimeout

        public void setReceiveTimeout​(int timeoutMillis)
                       throws NngException
        Set a receive timeout on the Context.
        Parameters:
        timeoutMillis - timeout in milliseconds
        Throws:
        NngException - on error setting the timeout

      • setSendTimeout

        public void setSendTimeout​(int timeoutMillis)
                    throws NngException
        Set a send timeout on the Context
        Parameters:
        timeoutMillis - timeout in milliseconds
        Throws:
        NngException - on error setting the timeout