Skip to content
/ umundo Public
forked from tklab-tud/umundo

Distributed Publish/Subscribe middleware for MacOSX, Linux, Windows, Android and iOS

License

Notifications You must be signed in to change notification settings

Memphiz/umundo

 
 

Repository files navigation

uMundo ReadMe

uMundo is a lightweight refactoring of the distributed Mundo publish/subscribe middleware to deliver byte arrays and objects on channels from publishers to subscribers. With lightweight, we do not necessarily refer to runtime behavior or memory footprint (though we work hard to keep it sane) but to the amount of code we have to maintain in order to arrive at a working system. It runs on Windows, Linux, Mac OSX, iOS devices and Android.

Other Documents
- Getting started
- Building from source
- Cross-Compiling for iOS and Android
- Setting up a test-slave
External Resources
- Build Reports
- Doxygen Documentation

License

uMundo itself is distributed under the Simplified BSD license.

Please have a look at the licenses of the libraries we depend upon as well.

Download

The fastest way to get started is to grab the uMundo SDK for your platform. It contains

  • uMundo libraries and headers
  • Available language bindings (build from source for PHP, Python or Perl bindings)
  • Android cross-compiled libraries
  • iOS cross-compiled libraries with the darwin installer
  • Templates for Eclipse, XCode and Visual Studio

Components

uMundo is divided into three components with different responsibilities in various stages of maturity:

umundo.core
The responsibility of umundo.core is to deliver messages from publishers to subscribers. A message contains foremost a raw byte array but can also be annotated with meta information as key/value pairs. It employs ZeroMQ to deliver byte arrays between nodes discovered via Bonjour or Avahi. The core is written in C++ and has bindings to CSharp, Java, Python, Perl, PHP and Objective-C. [more]

C++ Java Objective-C C# Python Perl PHP5
<dt><b>umundo.s11n</b></dt>
<dd>On top of the core, umundo.s11n offers object (de-)serialization using
<a href="http://code.google.com/p/protobuf/">Protocol Buffers</a>. As it is
unpractical to wrap the whole typing system via native access from other languages,
this component exists once for every target language. At the moment,
implementations for C++, Java, C# and Objective-C exist.<a href="/tklab-tud/umundo/tree/master/s11n">[more]</a>
<br/><br/><b>Note:</b> You can always access all of uMundos functionality from
Objective-C as you can just use .mm extensions and write mixed code. The biggest
stumbling block for umundo.s11n to have a pure Objective-C facade is the absence
of a suited protobuf compiler.
<br/><br/><table>
	<tr>
		<td style="border-right: solid #bbb 1px;">C++</td>
		<td style="border-right: solid #bbb 1px;">Java</td>
		<td style="border-right: solid #bbb 1px;">Objective-C</td>
		<td style="border-right: solid #bbb 1px;">C#</td>
	</tr>
</table>
</dd>

<dt><b>umundo.rpc</b></dt>
<dd>This component provides a service concept for remote procedure calls on top
of umundo.s11n. The new implementation features continuous service discovery with
pattern matching, but is only available in C++ and Java at the moment.
	<a href="/tklab-tud/umundo/tree/master/rpc">[more]</a>
<br/><br/><table>
	<tr>
		<td style="border-right: solid #bbb 1px;">C++</td>
		<td style="border-right: solid #bbb 1px;">Java</td>
		<td style="border-right: solid #bbb 1px;">Objective-C</td>
	</tr>
</table>
</dd>

Status

The authority on the state of uMundo is our build-server. The tests, while not numerous, are rather strict as there are plenty of asserts in the source code. We plan to add more test-slaves as they become available.

<tr><td>iOS 5.x / 6.x</td><td>
	<ul>
		<li>umundo.s11n uses the C++ generator as with Mac OSX.
		<li>The automated test are not executed on the build-server.
	</ul>
</td></tr>
<tr><td>Windows 7</td><td>
	<ul>
		<li>Everything builds and runs just fine with MS Visual Compiler and Visual Studio 10 and NMake.
		<li>We do not support MinGW as we would need precompiled libraries for our build-time dependencies. Feel free to put them as static libraries into contrib/prebuilt/ if you manage to compile them.
	</ul>
</td></tr>
<tr><td>Debian Linux 6.0.4</td><td>
	<ul>
		<li>Everything builds and runs just fine with GCC.
	</ul>
</td></tr>
<tr><td>Raspberry Pi</td><td>
	<ul>
		<li>Everything builds and runs just fine with GCC.
	</ul>
</td></tr>
<tr><td>Android 2.3</td><td>
	<ul>
		<li>Worked whenever we tried, but we cannot automatically test on the simulator, as <a href="http://developer.android.com/guide/developing/devices/emulator.html#emulatornetworking">google does not deem multicast to be important</a>.
		<li>The automated test are not executed on the build-server.
	</ul>
</td></tr>
PlatformIssues
Mac OSX 10.7
  • umundo.s11n employs the C++ generator for ProtoBuf as the various Objective-C generators are out of date (just use .mm file extensions).
<tr><td>Java</td><td>
	<ul>
		<li>No known issues.
	</ul>
</td></tr>

<tr><td>CSharp</td><td>
	<ul>
		<li>Make sure to use 64Bit on 64Bit systems.
		<li>No umundo.rpc implementation yet.
	</ul>
</td></tr>

<tr><td>Objective C</td><td>
	<ul>
		<li>No umundo.rpc implementation yet, just use <tt>.mm</tt> extensions and the C++ implementation.
	</ul>
</td></tr>

<tr><td>Python</td><td>
	<ul>
		<li>Only umundo.core is available.
		<li>Object instances get garbage collected if they leave scope.
		<li>Not part of the SDK yet.
		<li>Messages are not copied into runtime but destroyed when <tt>received</tt> returns.
	</ul>
</td></tr>

<tr><td>Perl</td><td>
	<ul>
		<li>Only umundo.core is available.
		<li>Object instances get garbage collected if they leave scope.
		<li>Not part of the SDK yet.
		<li>Messages are not copied into runtime but destroyed when <tt>received</tt> returns.
	</ul>
</td></tr>

<tr><td>PHP5</td><td>
	<ul>
		<li>Only umundo.core is available.
		<li>Object instances get garbage collected if they leave scope.
		<li>Not part of the SDK yet.
		<li>Messages are not copied into runtime but destroyed when <tt>received</tt> returns.
	</ul>
</td></tr>
Language BindingsIssues

Note: The scripting languages still have the problem of premature garbage collection. If you assign e.g. a Publisher to a Node, the node will only take the pointer to the underlying C++ object and not keep a reference to the language specific instance. This means that the respective garbage collectors will potentially remove these objects while they are still being used. This applies to all umundo.core objects.

FAQ

Why is the source distribution so large?
That's the price of convenience. The distribution contains most of our runtime dependencies prebuilt for every system / compiler combination and as debug and release builds.
<dt><b>How many umundo nodes can I realistically start at once?</b></dt>
<dd>Using the default ZeroMQ implementation and Bonjour discovery on MacOSX, I
	could start 32 umundo-pingpong instances before getting an <tt>Assertion
	failed: s != retired_fd (tcp_connecter.cpp:278)</tt> within ZeroMQ. I guess
	this is due to the rather low ulimit for open file-handles on MacOSX
	(<tt>ulimit -n</tt> gives 256).</dd>

<dt><b>Why am I not receiving messages?</b></dt>
<dd>There are a few things to check if you are not receiving published messages:
	<ul>
		<li>Are the subscriber and publisher added to different nodes?
		<li>Are the nodes in the same (or default) domain?
		<li>Does the channel name of the subscriber match the publisher's?
		<li>Is the publisher already connected to the subscriber? <br />
			<p style="padding-left: 1em;">You can use <tt>int Publisher.waitForSubscribers(int n)</tt> 
			to wait until <tt>n</tt> subscribers connected. The method will return the actual number of subscribers. Therefore,
			calling it with <tt>n = 0</tt> will not block and report the number of subscribers per publisher.</p>
	</ul>
</dd>

<dt><b>How do I use the language bindings?</b></dt>
<dd>All language bindings constitute of two components: 
	<ul>
	 	<li>a native extension named <tt>umundoNative&lt;LANGUAGE>&lt;LIB_SUFFIX></tt>.
		<li>a language specific wrapper that (loads and) provides access to this library.
	</ul>
	It depends on the actual language how to register/load extensions. There are a few 
	<a href="/tklab-tud/umundo/tree/master/examples">examples</a>. The exceptions are the 
	Java language bindings build for desktop systems, the JAR contains all required files.</dd>
	
<dt><b>Does uMundo support IPv6?</b></dt>
<dd>No, but only because I couldn't get ZeroMQ to compile with IPv6 on Android
	devices. Both ZeroConf implementations (Avahi and Bonjour) support IPv6 and
	we already gather these addresses (BonjourNodeStub and AvahiNodeStub). All
	that is needed is for both of these stubs to return an IPv6 address in
	<tt>getIP()</tt> and for ZeroMQ to be compiled with IPv6. The plan is to wait
	for another release of ZeroMQ 3.x and have another look.</dd>

<dt><b>Why do I get <tt>NullPointerException</tt>s when using custom ClassLoaders in a umundo callback?</b></dt>
<dd>Java has some strange issues with regard to custom class-loaders and JNI. This blog entry details the issue and 
	<a href="http://schnelle-walka.blogspot.de/2013/04/jni-causes-xml-parsing-problems-when.html">provides a workaround</a>.</dd>

<dt><b>Are these actually questions that are asked frequently?</b></dt>
<dd>No, it's more like a set of questions I can imagine other people might have. It will eventually grow into a real FAQ.</dd>	

About

Distributed Publish/Subscribe middleware for MacOSX, Linux, Windows, Android and iOS

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published