Asynchronous Message Processing

The AMPS C# client also supports an asynchronous interface. In this case, you add a message handler to the call to the subscribe. The client returns the command ID of the command submitted to AMPS, and returns once the server has acknowledged that the command has been processed. As messages arrive, AMPS calls your message handler directly on the background thread. This can be an advantage for some applications. For example, if your application is highly multithreaded and copies message data to a work queue processed by multiple threads, there may be a performance benefit to enqueuing work directly from the background thread. See the Understanding Threading section for a discussion of threading considerations, including considerations for message handlers.

As with the simple interface, the AMPS client provides both convenience interfaces and interfaces that use a Command object. The following example shows how to use the asynchronous interface.

class MyApp
{
    public static void Main()
    {
        // Here, we create a Client. We protect the Client in a
        // using block so that the connection and subscriptions
        // are properly cleaned up when dispose() is called.
        using(Client client = new Client("subscribe"))
        {
            client.connect("tcp://127.0.0.1/9007/amps");
            client.logon();

            Command command = new Command("subscribe").setTopic("messages");

            // Here, we call the executeAsync() method, specifying the command and
            // the message handler to invoke with messages received in response to
            // the command.
            CommandId subscriptionId = c.executeAsync(command, (message) => Console.WriteLine(message.Data));

            // (message) => Console.WriteLine(message.Data) is a lambda function
            // that acts as our message handler. When a message is received, this
            // lambda function is invoked, and in this case, the Data property from
            // message is printed to the screen. Message is of type AMPS.Client.Message.
        }
    }
}

In the asynchronous interface, the AMPS client resets and reuses the message object provided to this lambda function between calls. This improves performance in the client, but means that if your handler function needs to preserve information contained within the message, you must copy the information rather than just saving the message object. Otherwise, the AMPS client cannot guarantee the state of the object or the contents of the object when your program goes to use it.