C++ Client API

powerful. fast. easy.

Building a high-performance messaging application in C++? Use AMPS along with the AMPS C/C++ Client to build robust, blazing fast applications for Windows and Linux. Here's a few examples to get you started:

Example 1: Connect and Subscribe

Connecting and subscribing to a content-filtered topic couldn't be easier:

 1 #include <amps.h>
 2 #include <iostream>
 3     ...
 4     int main()
 5     {
 6       AMPS::Client amps("myapp");
 8       try
 9       {
11         amps.connect("tcp://localhost:9007/amps/json");
12         amps.logon();
14         for (auto msg : amps.subscribe("orders",
15                                        "/symbol LIKE 'ABCD'"))
16         {
18            std::cout << msg.getData() << std::endl;
20         }
22       } catch (AMPSException &e) {
23         std::cerr << e.what() << std::endl;
24         return -1;
25       }
26       return 0;
27     }

In this example, we connect to AMPS and subscribe to the "orders" topic. Messages are filtered on the server: we're only sent messages whose "symbol" field contains "ABCD". As messages arrive, the program prints messsage data to the console. If any errors occur while connecting or subscribing, they're printed to the console as well.

Example 2: Automatic Reconnection and Resubscription

Rock-solid applications must be able to recover from network outages. The AMPS C++ client includes an HAClient class that includes automatic reconnection and resubscription. Best of all, easy-to-implement interfaces control reconnection and resubscription behavior, allowing you to easily customize failover.

 1 AMPS::HAClient client("reconnectingSubscriber");
 3 // The ServerChooser interface tells the HAClient which server
 4 // to connect to, both for the initial connection and failover.
 5 // The DefaultServerChooser is included with the client: many
 6 // applications implement a ServerChooser to control failover
 7 // behavior.
10 AMPS::ServerChooser chooser(new AMPS::DefaultServerChooser());
11 chooser.add("tcp://amps-server:9007/amps/json");
12 chooser.add("tcp://amps-failover-server:9007/amps/json");
14 client.setServerChooser(chooser);
15 client.connectAndLogon();
18 // Enter subscriptions. If the connection to the server
19 // is lost, the HAClient will restore the connection to
20 // the server or the failover partner, and restore
21 // subscriptions.
22 client.subscribe(AMPS::MessageHandler(handler_function, NULL),
23                  "my-cool-topic");

The HAClient class can, optionally, also provide store-and-forward for reliable publish. With the AMPS transaction log, the class can provide resumable subscriptions that are guaranteed not to miss messages or receive duplicate messages, even in the case of failover between replicated servers. See the C++ Developer Guide for more information on enabling these capabilities of the HAClient (and other options for the class).

Also, notice that message handlers can be specified using C++ function objects (including lambda functions) for type-safety, or using raw function pointers as in this example.

Example 3: Query the Contents of a "SOW" Topic

State-of-the-World ("SOW") topics in AMPS combine the power of a database table with the performance of a publish-subscribe system. Use the AMPS C/C++ Client to query the contents of a SOW topic, and retrieve ongoing updates:

 1 class MyApp {
 2       std::map<std::string, std::string> _data;
 3       AMPS::Client _client;
 5       void handleMessage(const Message& m) {
 6         if(m.getCommand()=="oof") {
 7           _data.remove(m.getSowKey());
 8         } else if(m.getCommand()=="sow" ||
 9                   m.getCommand()=="publish") {
10           _data[m.getSowKey()] = m.getData();
11         }
12       }
14       public:
15       void run() {
17         auto messageHandler = [&](const AMPS::Message& m)
18                                   { handleMessage(m); } ;
20         _client.executeAsync(
21                          Command("sow_and_subscribe").
22                              setTopic("orders").
23                              setFilter("/symbol LIKE 'ABC' "
24                                        "AND /qty > 100").
25                              setOptions("oof"),
26                          messageHandler);
27                  );
28       }
29     }

In this example, we keep a local std::map up to date with the changes in an AMPS topic. Our message handler is called once for each row in the initial result set for our query of "orders." After that, it continues to be called each time any attribute of the order changes, with the Command set to "publish." When an order is no longer present in the orders topic, our handler is called with a message that has a Command of "oof."

Notice that, in this example, all of the processing occurs on a background thread. Many high performance applications receive messages on one thread, and enqueue those messages to be processed by worker threads. The AMPS C++ client includes an asynchronous interface that makes it easy to build high-performance multithreaded programs that follow this pattern.

Everything You Need

Ready to learn more? The AMPS C/C++ Client includes everything you need to get started: libraries, sample applications, developer's guide, and reference documentation. Each AMPS Client includes complete source code so you can fully learn and understand AMPS, and best integrate it into your environment.

Click here (Linux) or here (Windows) to download and start using the AMPS C/C++ Client. Once you've downloaded it, read the Developer Guide to get started.

The current release of the C++ client is version, which supports AMPS servers version 5.3 and earlier.