PonyExpress

Downloads

pexpr-0.4.3.tar.gz

Overview

Pony Express is a cross-platform library providing inter-module, inter-application, and inter-computer communication. Using Pony Express you can develop modular applications that do not depend on sharing the same process space. Pony Express uses a Post Office metaphore where your modules register POBoxes that can be used to send messages to eachother. Once two applications are connected your application no longer needs to concern itself with whether or not a module is within the same process space, on the same computer or across the network. You no longer have to maintain socket connections, packetize your data, and manage other low level details associated with network programming. You can seemelessly connect different architectures using different byte ordering network libraries.

Pony Express works under Linux, Mac OS X, and IRIX and requires the Qt library by TrollTech.

how to

Dependancies:

Pony Express uses the Qt library by Troll Tech for several reasons. The first is that Qt provides a platform independent socket interface. Secondly, many of our other applications also use Qt for GUIs. Lastly, the signal-slot architecture provides a beautiful object oriented interface to callbacks allowing applications to find out when you have new messages instead of polling.

How To:

We will show some of the abilities of the Pony Express system in the following example. The example code shows a simple text message transmission and reception. The API was designed with ease of use in mind, and usually takes only a few lines of code per code block.

We will begin with the sending program:

Client.cpp

--------------------------------------------------------------

#include <PostOffice.h>

#include <POTextMsg.h>

#include <qapplication.h>

int main( int argc, char **argv )

{
// Standard Qt program, a QApplication must be created for the Qt

    // functionality

    QApplication *Qapp = new QApplication(argc, argv, false);

// Message to be sent

    POTextMsg msg("Hello World!");

// Initialize the Post Office that will be used by the client

    // A unique name must be selected for each client

    // A Qapplication needs to be running at this point to process

    // socket events

    PostOffice *poffice = new PostOffice("Client Office");

// Connect to the server to setup the connection to transfer the

    // messages and register a PO Box at the server.  The server will

    // be listening on port 8000(see receiver.cpp).

    // ConnectTo will return the name of the server's Post Office,

    // this is used when sending messages.

    string server_poname = poffice->connectTo( "localhost", 8000);

// Now that we've connected to the server's Post Office

    // let's register a PO Box.  You need to do this so that the

    // receiver has a valid return address.

    POBox* clientbox = poffice->registerPOBox( "Client POBox" );

// Spamming loop

    while ( 1 )

    {

        // Now to send the POTextMsg that we created above.

        // Give it a pointer to your message and the POAddress you want 

        // to send it to.  The POAddress is a two part address, the Post

        // Office followed by the POBox.  In this case we know the

        // receiver's POBox name will be "Server POBox" and we know

        // the Office's name from the server_poname returned.

        clientbox->sendMessage( &msg, POAddress( server_poname,
 
                                 "Server POBox" ) );

        // One sec delay so we don't completely spam the server

        // with "Hello World!

        usleep(1000000);

        // Allow Qt Events to run

        Qapp->processEvents();

    }

    return 0;

}

--------------------------------------------------------------

As you can see, to setup the interface took 3 Lines, and sending the message took 1 line.

Now lets see what it takes to receive the message we just sent:

Reciever.cpp

--------------------------------------------------------------

#include <PostOffice.h>

#include <POTextMsg.h>

#include <qapplication.h>

#include <iostream>

using namespace std;

int main(int argc, char **argv)

{

    QApplication *Qapp = new QApplication(argc, argv, false);

    PostOffice* poffice = new PostOffice("Server Office");
//  The server will listen on port 8000, or any other port, 

	// to listen on.

    poffice->servicePort( 8000 );

    POBox* servbox = poffice->registerPOBox("Server POBox");

	while( 1 )

    {
// Check our messages

        // You may have more than one message, so we want to keep

        // checking until we get all of them.

        while( servbox->hasMessages() )

        {
// pop the oldest message from your mail box

            const POMessage* msg = servbox->popMessage();

// check its type, by convention the type will be a string

            // that matches the class name

            if( msg->messageType() == "POTextMsg" )

            cout << "Recieved Message: "

                << ((const POTextMsg*)msg)->getText()

                << endl;

// Receiver is responsible for deleting its own mail

            delete msg;

        }

// sleep and allow Qt Events to run.

        usleep(10);

        Qapp->processEvents();

    }

    return 0;

}

--------------------------------------------------------------

If you wanted to use groups in this example:

In the client code add:

// after the connectTo line

clientbox->joinGroup( POAddress( server_poname, "Group name") );

In the receiver code add:

// after servicePort

poffice->registerGroup( "Group name" );

and to send a message, instead of "Server POBox" you would use "Group name".

To try these samples yourself:

Download the client program and server programs into different directories
Run qmake -project
Run qmake
Run make
The path to the Pony Express Library will have to be in your LD_LIBRARY_PATH variable, so export LD_LIBRARY_PATH=/usr/local/lib
Repeat in the other directory
Run the server, Run the client. This should create a "Received Message: Hello World!" appear once a second on the server's terminal.