- Table of Contents
- 1. Introduction
- 2. LBM Binary Use
- 3. LBM Programming Use
- 4. Next Step
This document provides step-by-step instructions on how to rapidly get started using 29West Latency Busters® Messaging (LBM), a fast, efficient, and lightweight messaging system targeted specifically at high performance systems with demanding applications.
1. Introduction
This document gets you started using our pre-compiled evaluation binaries to test performance, and then walks you through the steps of writing minimal source (sender) and receiver applications.
If you have any questions or comments, please contact us at Support@29West.Com.
2. LBM Binary Use
An LBM software evaluation kit. consists of the documentation package (which includes this document) and one or more binary packages. These instructions will help get you started evaluating LBM quickly. You can run pre-compiled commands from an LBM binary distribution to get some quick performance numbers in your environment. (A subsequent section guides you through creation of simple programs for local compilation.)
A binary package consists of:
-
Binary versions of source code examples (see the bin directory)
-
Header files (see the include directory)
-
Link libraries (see the lib directory)
-
Shared libraries (see the lib directory on Unix for .so files or the bin directory on Windows for .dll files)
The LBM code and documentation are copyrighted and confidential information owned by 29West Inc. and are covered under the terms of our Software License Agreement or Non-Disclosure Agreement as appropriate. Use of this code and documentation without a valid Non-Disclosure Agreement or Software License Agreement with 29West Inc. is strictly prohibited. If this code and documentation is being supplied under the terms of a Non Disclosure Agreement, all copies, in any form, must be returned or destroyed at the end of the evaluation period or as requested by 29West Inc.
2.1. LBM Binary Use on Windows
The following steps assume that the windows package is installed on all test machines in the standard place:
C:\Program Files\29West\LBM_rel-id\Win2k-i386
where rel-id is the release identifier. It is also assumed that the \bin directory is included in the windows PATH environment variable. This is needed so that the .EXE and .DLL files can be found.
-
Open a command prompt window on the machine you want to use for receiving messages and enter the command lbmrcv topic to start a receiver. Note that topic can be any string. You should see output that looks something like this:
1.006 secs. 0.0 Kmsgs/sec. 0.0 Kbps 1.019 secs. 0.0 Kmsgs/sec. 0.0 Kbps 1.010 secs. 0.0 Kmsgs/sec. 0.0 Kbps
A new line will be printed about once per second showing the elapsed time, messages received, and data received. As long as there are no sources yet running on topic, the number of messages received will continue to be zero.
-
Open a command prompt window on the machine you want to use for sending messages and enter the command lbmsrc topic to start sending messages. The receiver will automatically discover the source, at which time its output will change to something like this:
1.010 secs. 451.9 Kmsgs/sec. 90.4 Mbps 1.010 secs. 451.4 Kmsgs/sec. 90.3 Mbps 1.010 secs. 445.1 Kmsgs/sec. 89.0 Mbps
-
With no options given, the source will send 10,000,000 small (25 byte) messages. If you would like to test different size packets or number of packets sent, you can set options. Enter lbmsrc -h at the command line, you will get a list of options you can control.
-
Press Ctrl-C to kill the source or receiver.
2.2. LBM Binary Use on Unix
The following steps assume that the Unix package is installed on all test machines under a normal user account:
/home/user-id/lbmeval/LBM_rel-id/platform-id
where rel-id is the release identifier and platform-id describes the ABI (Application Binary Interface - e.g. Linux-2.4-glibc-2.2-i686). It is also assumed that the /bin directory is included in the PATH environment variable and the /lib directory is in the appropriate loader library search path environment variable (e.g. LD_LIBRARY_PATH for Solaris).
-
Open a command prompt window on the machine you want to use for receiving messages and enter the command lbmrcv topic to start a receiver. Note that topic can be any string. You should see output that looks something like this:
1.006 secs. 0.0 Kmsgs/sec. 0.0 Kbps 1.019 secs. 0.0 Kmsgs/sec. 0.0 Kbps 1.010 secs. 0.0 Kmsgs/sec. 0.0 Kbps
A new line will be printed about once per second showing the elapsed time, messages received, and data received. As long as there are no sources yet running on topic, the number of messages received will continue to be zero.
-
Open a command prompt window on the machine you want to use for sending messages and enter the command lbmsrc topic to start sending messages. The receiver will automatically discover the source, at which time its output will change to something like this:
1.010 secs. 451.9 Kmsgs/sec. 90.4 Mbps 1.010 secs. 451.4 Kmsgs/sec. 90.3 Mbps 1.010 secs. 445.1 Kmsgs/sec. 89.0 Mbps
-
With no options given, the source will send 10,000,000 small (25 byte) messages. If you would like to test different size packets or number of packets sent, you can set options. Enter lbmsrc -h at the command line, you will get a list of options you can control.
-
Press Ctrl-C to kill the source or receiver.
3. LBM Programming Use
The programs below contain the minimum code and supporting material. Their purpose is to verify that the user's build and run-time environments are set up correctly. They also give a basic introduction to the LBM API.
This source code example is provided by 29West for educational and evaluation purposes only.
3.1. Minimal LBM Source Implementation
This is a source code listing of a minimal source (sender) program. You may find it helpful to download the source code (most browsers let you right-click on the link and use the save link target function, or some variation).
/*file: minsrc.c - minimal source (sender) program.
*
* Copyright (c) 2005-2007 29West, Inc. Permission is granted to licensees to use
* or alter this software for any purpose, including commercial applications,
* according to the terms laid out in the Software License Agreement.
*/
#include <stdio.h>
#if defined(_MSC_VER)
/* Windows-only includes */
#include <winsock2.h>
#define SLEEP(s) Sleep((s)*1000)
#else
/* Unix-only includes */
#include <stdlib.h>
#include <unistd.h>
#define SLEEP(s) sleep(s)
#endif
#include <lbm.h>
main()
{
lbm_context_t *ctx; /* pointer to context object */
lbm_topic_t *topic; /* pointer to topic object */
lbm_src_t *src; /* pointer to source (sender) object */
int lbm_failed; /* return status of lbm functions */
#if defined(_MSC_VER)
/* windows-specific code */
WSADATA wsadata;
int wsStat = WSAStartup(MAKEWORD(2,2), &wsadata);
if (wsStat != 0) {printf("line %s: %d\n", __LINE__, wsStat); exit(1);}
#endif
lbm_failed = lbm_context_create(&ctx, NULL, NULL, NULL); 
if (lbm_failed) {printf("line %s: %s\n", __LINE__, lbm_errmsg()); exit(1);}
lbm_failed = lbm_src_topic_alloc(&topic, ctx, "Greeting", NULL); 
if (lbm_failed) {printf("line %s: %s\n", __LINE__, lbm_errmsg()); exit(1);}
lbm_failed = lbm_src_create(&src, ctx, topic, NULL, NULL, NULL); 
if (lbm_failed) {printf("line %s: %s\n", __LINE__, lbm_errmsg()); exit(1);}
SLEEP(3); 
lbm_failed = lbm_src_send(src, "Hello!", 6, LBM_MSG_FLUSH | LBM_SRC_BLOCK); 
if (lbm_failed) {printf("line %s: %s\n", __LINE__, lbm_errmsg()); exit(1);}
SLEEP(2); 
/* Finished all sending to this topic, delete the source object. */
lbm_src_delete(src);
/* Do not need to delete the topic object - LBM keeps track of topic
* objects and deletes them as-needed. */
/* Finished with all LBM functions, delete the context object. */
lbm_context_delete(ctx);
#if defined(_MSC_VER)
WSACleanup();
#endif
} /* main */
3.1.1. Notes:
- Create a context object. A context is an environment in which LBM functions. Note that the first parameter is a pointer to a pointer variable; lbm_context_create writes the pointer to the context object into "ctx". Also, by passing NULL to the context attribute parameter, the default option values are used.
- Allocate a topic object. A topic object is little more than a string (the topic name). During operation, LBM keeps some state information in the topic object as well. The topic is bound to the containing context, and will also be bound to a source object. Note that the first parameter is a pointer to a pointer variable; lbm_src_topic_alloc writes the pointer to the topic object into "topic". Also, by passing NULL to the source topic attribute, the default option values are used. The string "Greeting" is the topic string.
- Create the source object. A source object is used to send messages. It must be bound to a topic. Note that the first parameter is a pointer to a pointer variable; lbm_src_create writes the pointer to the source object to into "src". Use of the third and fourth parameters is optional but recommended in a production program - some source events can be important to the application. The last parameter is an optional event queue (not used in this example).
- Need to wait for receivers to find us. See LBM application note: doc/AppNotes/delay-before-sending.html for details.
- Send a message to the "Greeting" topic. The flags make sure the call to lbm_src_send doesn't return until the message is sent.
- Even though the message is sent, some transports may need a bit of time to request re-transmission. If the above lbm_src_send call didn't include the flags, some time might also be needed to empty the batching buffer.
3.2. Minimal LBM Receiver Implementation
This is a source code listing of a minimal receiver program. You may find it helpful to download the source code (most browsers let you right-click on the link and use the save link target function, or some variation).
/*file: minrcv.c - minimal receiver program. * * Copyright (c) 2005-2007 29West, Inc. Permission is granted to licensees to use * or alter this software for any purpose, including commercial applications, * according to the terms laid out in the Software License Agreement. */ #include <stdio.h> #if defined(_MSC_VER) /* Windows-only includes */ #include <winsock2.h> #define SLEEP(s) Sleep((s)*1000) #else /* Unix-only includes */ #include <stdlib.h> #include <unistd.h> #define SLEEP(s) sleep(s) #endif #include <lbm.h> /* * A global variable is used to communicate from the receiver callback to * the main application thread. */ int msgs_rcvd = 0; int app_rcv_callback(lbm_rcv_t *rcv, lbm_msg_t *msg, void *clientd)
3.2.1. Notes:
- LBM passes received messages to the application by means of a callback. I.e. the LBM context thread reads the network socket, performs its higher-level protocol functions, and then calls an application-level function that was set up during initialization. This callback function has some severe limitations placed upon it. It must execute very quickly; any potentially blocking calls it might make will interfere with the proper execution of the LBM context thread. One common desire is for the receive function to send an LBM message (via lbm_src_send), however this has the potential to produce a deadlock condition. If it is desired for the receive callback function to call LBM or other potentially blocking functions, it is strongly advised to make use of an event queue, which causes the callback to be executed from an application thread. See the example tool lbmrcvq.c for an example of using a receiver event queue.
- Note - printf can block, which is normally a bad idea for a callback (unless an event queue is being used). However, for this minimal application, only one message is expected.
- Create a context object. A context is an environment in which LBM functions. Note that the first parameter is a pointer to a pointer variable; lbm_context_create writes the pointer to the context object into "ctx". Also, by passing NULL to the context attribute parameter, the default option values are used.
- Lookup a topic object. A topic object is little more than a string (the topic name). During operation, LBM keeps some state information in the topic object as well. The topic is bound to the containing context, and will also be bound to a receiver object. Note that the first parameter is a pointer to a pointer variable; lbm_rcv_topic_lookup writes the pointer to the topic object into "topic". Also, by passing NULL to the source topic attribute, the default option values are used. The string "Greeting" is the topic string.
- Create the receiver object and bind it to a topic. Note that the first parameter is a pointer to a pointer variable; lbm_rcv_create writes the pointer to the source object to into "rcv". The second and third parameters are the function and application data pointers. When a message is received, the function is called with the data pointer passed in as its last parameter. The last parameter is an optional event queue (not used in this example).
4. Next Step
If you have applications that could use a higher performance messaging layer, we invite you to perform a risk-free software evaluation. We provide you with full code, documentation, and support for you to integrate LBM into your application. See for yourself how we measure up.