README.build

Building the client

Running `make` produces the CPP client tarball that is available
for download on the voltdb.com website. A static library (libvoltdbcpp.a)
is written at the working tree root. A shared library (libvoltdbcpp.so)
is written at the working tree root.

Running `make test` executes the CPP unit tests. You should expect
to see all tests pass with output similar to:

  Running CPPUnit tests
  ./testbin
  .........................................................

  OK (57 tests)

By default, libevent-2.0.x is included in the soure tree as a tar.gz
file. The script build_libevent.sh builds libevent from this tarball
as part of the usual build process. You can use a different (2.x)
version of libevent - simply replace the libevent tarball.


Running the tests

The tests require CPPUnit. You can install cppunit on ubuntu with the
command: `apt-get install libcppunit-dev`

Once you have built either version of the shared library you can build the
tests using the makefile in Tests and then run the Tests executable that is
build. It is highly recommended that you run the tests under valgrind using
"valgrind --leak-check=full --show-reachable=yes". The application should exit
with all heap blocks freed. If you are running with the debug library there
will be two errors generated by some global state in libevent and these are
safe to ignore.  Sometimes a block is retained somewhere in libc, but it
doesn't always show up. The library itself should not retain any memory.

Note that if you already have a VoltDB server running, the tests will fail.
Kill the server and try again.

API description

The C++ client API is single threaded. The shared pointers that are returned
are not thread safe and the Client instances are not thread safe. Because it is
single threaded your application has to provide its thread to the API to do
network IO and invoke callbacks. At key points your application can call run()
to enter an event loop that will not exit until a callback returns true or one
of the status listener notificaiton methods returns true. An application can
also call runOnce() or spin in a loop on runOnce(). runOnce() does network IO
and invokes callbacks, but returns immediately after all pending events have
been handled.

Unlike the Java client library the C++ library is relatively lightweight
(creates no additional threads) so you can instantiate multiple instances on a
single host. If you find you need more parallelism you should consider creating
multiple threads, each with a dedicated client instance, and connect each
instance to a different subset of the cluster. A single thread should be able
to saturate gig-e.

Known Issues

One of the serialization tests doesn't pass when compiled and run on Ubuntu
10.04 32-bit. The problem is specific to the serialization of Decimal values.
Avoid using Decimal values on 32-bit platforms until CLIENTAPI-2 is fixed.
https://issues.voltdb.com/browse/CLIENTAPI-2

Uncaught exception handler may be provided with the wrong procedure callback
pointer if it ends up being wrapped internally. The wrapper is provided instead
of the callback. See https://issues.voltdb.com/browse/CLIENTAPI-33