164 lines
7.6 KiB
Plaintext
164 lines
7.6 KiB
Plaintext
Zookeeper C client library
|
|
|
|
|
|
This package provides a C client interface to Zookeeper server.
|
|
|
|
For the latest information about ZooKeeper, please visit our website at:
|
|
http://zookeeper.apache.org/
|
|
and our wiki, at:
|
|
https://cwiki.apache.org/confluence/display/ZOOKEEPER
|
|
|
|
Full documentation for this release can also be found in ../../docs/index.html
|
|
|
|
|
|
OVERVIEW
|
|
|
|
The client supports two types of APIs -- synchronous and asynchronous.
|
|
|
|
Asynchronous API provides non-blocking operations with completion callbacks and
|
|
relies on the application to implement event multiplexing on its behalf.
|
|
|
|
On the other hand, Synchronous API provides a blocking flavor of
|
|
zookeeper operations and runs its own event loop in a separate thread.
|
|
|
|
Sync and Async APIs can be mixed and matched within the same application.
|
|
|
|
The package includes two shared libraries: zookeeper_st and
|
|
zookeeper_mt. The former only provides the Async API and is not
|
|
thread-safe. The only reason this library exists is to support the
|
|
platforms were pthread library is not available or unstable
|
|
(i.e. FreeBSD 4.x). In all other cases the application developers are
|
|
advised to link against zookeeper_mt as it includes support for both
|
|
Sync and Async API.
|
|
|
|
|
|
INSTALLATION
|
|
|
|
If you're building the client from a source checkout you need to
|
|
follow the steps outlined below. If you're building from a release
|
|
tar downloaded from Apache please skip to step 2.
|
|
|
|
1) do a "ant compile_jute" from the zookeeper top level directory (.../trunk).
|
|
This will create a directory named "generated" under zookeeper-client/zookeeper-client-c.
|
|
Skip to step 3.
|
|
2) unzip/untar the source tarball and cd to the zookeeper-x.x.x/zookeeper-client/zookeeper-client-c directory
|
|
3) change directory to zookeeper-client/zookeeper-client-c and do a "autoreconf -if" to bootstrap
|
|
autoconf, automake and libtool. Please make sure you have autoconf
|
|
version 2.59 or greater installed. If cppunit is installed in a non-standard
|
|
directory, you need to specify where to find cppunit.m4. For example, if
|
|
cppunit is installed under /usr/local, run:
|
|
|
|
ACLOCAL="aclocal -I /usr/local/share/aclocal" autoreconf -if
|
|
|
|
4) do a "./configure [OPTIONS]" to generate the makefile. See INSTALL
|
|
for general information about running configure. Additionally, the
|
|
configure supports the following options:
|
|
--enable-debug enables optimization and enables debug info compiler
|
|
options, disabled by default
|
|
--without-syncapi disables Sync API support; zookeeper_mt library won't
|
|
be built, enabled by default
|
|
--disable-static do not build static libraries, enabled by default
|
|
--disable-shared do not build shared libraries, enabled by default
|
|
--without-cppunit do not build the test library, enabled by default.
|
|
|
|
5) do a "make" or "make install" to build the libraries and install them.
|
|
Alternatively, you can also build and run a unit test suite (and
|
|
you probably should). Please make sure you have cppunit-1.10.x or
|
|
higher installed before you execute step 4. Once ./configure has
|
|
finished, do a "make check". It will build the libraries, build
|
|
the tests and run them.
|
|
6) to generate doxygen documentation do a "make doxygen-doc". All
|
|
documentations will be placed to a new subfolder named docs. By
|
|
default only HTML documentation is generated. For information on
|
|
other document formats please use "./configure --help"
|
|
|
|
Alternatively you can use the CMake build system. On Windows, this is required.
|
|
Follow steps 1 and 2 above, and then continue here.
|
|
|
|
1) do a "cmake [OPTIONS]" to generate the makefile or msbuild files (the correct
|
|
build system will be generated based on your platform). Some options from above
|
|
are supported:
|
|
-DCMAKE_BUILD_TYPE Debug by default, Release enables optimzation etc.
|
|
-DWANT_SYNCAPI ON by default, OFF disables the Sync API support
|
|
-DWANT_CPPUNIT ON except on Windows, OFF disables the tests
|
|
-DWITH_OPENSSL ON by default, OFF disables the SSL support. You can also
|
|
specify a custom path by -DWITH_OPENSSL=/path/to/openssl/
|
|
-DBUILD_SHARED_LIBS not yet supported, only static libraries are built
|
|
other CMake options see "cmake --help" for generic options, such as generator
|
|
|
|
2) do a "cmake --build ." to build the default targets. Alternatively you can
|
|
invoke "make" or "msbuild" manually. If the tests were enabled, use "ctest -V"
|
|
to run them.
|
|
|
|
Current limitations of the CMake build system include lack of Solaris support,
|
|
no shared library option, no explicitly exported symbols (all are exported by
|
|
default), no versions on the libraries, and no documentation generation.
|
|
Features of CMake include a single, easily consumed cross-platform build system
|
|
to generate the ZooKeeper C Client libraries for any project, with little to no
|
|
configuration.
|
|
|
|
EXAMPLE/SAMPLE C CLIENT SHELL
|
|
|
|
NOTE: the ZooKeeper C client shell (cli_st and cli_mt) is meant as a
|
|
example/sample of ZooKeeper C client API usage. It is not a full
|
|
fledged client and not meant for production usage - see the Java
|
|
client shell for a fully featured shell.
|
|
|
|
You can test your client by running a zookeeper server (see
|
|
instructions on the project wiki page on how to run it) and connecting
|
|
to it using the zookeeper shell application cli that is built as part
|
|
of the installation procedure.
|
|
|
|
cli_mt (multithreaded, built against zookeeper_mt library) is shown in
|
|
this example, but you could also use cli_st (singlethreaded, built
|
|
against zookeeper_st library):
|
|
|
|
$ cli_mt zookeeper_host:9876
|
|
|
|
To start a client with read-only mode enabled, use the -r flag:
|
|
|
|
$ cli_mt -r zookeeper_host:9876
|
|
|
|
This is a client application that gives you a shell for executing
|
|
simple zookeeper commands. Once successfully started and connected to
|
|
the server it displays a shell prompt.
|
|
|
|
You can now enter zookeeper commands. For example, to create a node:
|
|
|
|
> create /my_new_node
|
|
|
|
To verify that the node's been created:
|
|
|
|
> ls /
|
|
|
|
You should see a list of nodes who are the children of the root node "/".
|
|
|
|
Here's a list of command supported by the cli shell:
|
|
|
|
ls <path> -- list children of a znode identified by <path>. The
|
|
command set a children watch on the znode.
|
|
get <path> -- get the value of a znode at <path>
|
|
set <path> <value> -- set the value of a znode at <path> to <value>
|
|
create [+e|+s] <path> -- create a znode as a child of znode <path>;
|
|
use +e option to create an ephemeral znode,
|
|
use +s option to create a znode with a sequence number
|
|
appended to the name. The operation will fail if
|
|
the parent znode (the one identified by <path>) doesn't
|
|
exist.
|
|
delete <path> -- delete the znode at <path>. The command will fail if the znode
|
|
has children.
|
|
sync <path> -- make sure all pending updates have been applied to znode at <path>
|
|
exists <path> -- returns a result code indicating whether the znode at <path>
|
|
exists. The command also sets a znode watch.
|
|
myid -- prints out the current zookeeper session id.
|
|
quit -- exit the shell.
|
|
|
|
In order to be able to use the zookeeper API in your application you have to
|
|
1) remember to include the zookeeper header
|
|
#include <zookeeper/zookeeper.h>
|
|
2) use -DTHREADED compiler option to enable Sync API; in this case you should
|
|
be linking your code against zookeeper_mt library
|
|
|
|
Please take a look at cli.c to understand how to use the two API types.
|
|
(TODO: some kind of short tutorial would be helpful, I guess)
|