Back to files

libpubsub

Abstract

Tiny PUBlish/SUBscribe server/library. The message protocol is plain ASCII. The message keys are also plain ASCII strings (message keys are necessary to subscribe to certain messages). Network transport is achieved over UDP or TCP. Binary data can be converted to a string representation. At the moment, there is no authentication.

Introduction

There are many usecases for libpubsub. In short, it works like this: 1) The pubsub message broker (psb, part of the tools) is launched.

It receives UDP/TCP messages at port 55355 (you can easily change this in

the sources).
2) One or more pubsub clients are launched. They may subscribe themselves to one

or more message keys and/or publish messages marked with a specific message key.
3) The message broker receives all published messages from the clients and

forwards them to all interested clients.

This way it is very easy to let many (don't know exactly how libpubsub behaves with very many clients at the moment) processes communicate with each other in a very fast manner. It does not matter, if they run on a single machine or are distributed on several remote hosts.

Two additional tools are part of this package: - psdump
This is a simple pubsub client, which subscribes for all message keys and dumps them to stdout.
- psc
This is a simple pubsub client, which makes it even easier for i.e. shell

scripts to participate in a pubsub group.

libpubsub makes it easy to develop pubsub clients with c++.

All pubsub clients automatically try to determine the address of the message broker by evaluating the environment variable PUBSUB_BROKER. It's format is: "HOST:PORT:SERVICE". HOST may be an ip address or symbolic hostname. SERVICE may be "udp" or "tcp" at the moment.

Hope this short introduction could make a bit clear what libpubsub is good for. If not, don't hesitate to ask me ;-)

API

The documentation of the libpubsub API is now pregenerated in doc/html. No special tool (doxygen, graphviz, tcm) is required.

Hidden in the documentation you may find a user's guide to libpubsub. It contains some small and simple examples which should make things clearer.

Additional Installation Notes

This release makes it even easier to install libpubsub, as the dependency on the cppsocket library has been removed.

1. ./configure
2. make

If everything worked well, you find a simple chat example in the examples/chat directory. If you start the message broker (tools/psb) in a separate terminal, you may chat with yourself by starting the chat client (examples/chat/client) twice (in two terminals). Note that the client is very simple and receives new messages only after you've sent something. If you want to see what the message broker is sending, launch tools/psdump, too.

If you want to run some tests (and have installed the unit++ test framework from http://unitpp.sourceforge.net/) do step 3, otherwise continue with step 4.

3) make test

4) make install

This installs the pubsub-tools (psb, psdump, psc) and the shared library.

Limitations

It is not possible to send arbitrary large messages in a mixed transport environment at the moment.

If you use UDP, the total size of a single message may not exceed the maximum UDP packet size, which results in a maximum message of 65507 bytes. Depending on your message key and the value of the validity, a payload of up to 65503 bytes is possible. But this covers only sending of UDP packets. On the receiver's side there are also limitations: Mainly the receivers buffer. A payload of 550 bytes is guaranteed to be received. Other problems may arise by fragmentation, which occures for packets larget than the MTU of the traversed networks (i.e. 1500 bytes for ethernet).

If all participating clients are connected to the message broker via TCP, it is possible to send large messages. It is no problem if clients are connected via UDP as long as they are not subscribed for message keys which could result in large messages.

Other solutions

Before I decided to create libpubsub I searched the net several days for something like libpubsub. I've found two packages which may also be used for interprocess communication over networks: - xmlBlaster
- jabber

But the first was much to complex and oversized for my purposes (beside the fact, that the c++ part was not in a very usable state and needed many other libraries to do something).

The second was smaller but also too powerful for my simple needs. The publish/subscribe part of jabber was in a very experimental state.

So if libpubsub does not do what you want, and you are willing to spent several hours (days?) in exploring and understanding xmlBlaster or jabber, just do it :-)

But I think, you should give libpubsub a try ;-))

Credits

Many thanks go to the following people: - murray smigel, for feedback and trying libpubsub with cygwin