| 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 src/c. Skip to step 3. |
| 2) unzip/untar the source tarball and cd to the zookeeper-x.x.x/src/c directory |
| 3) change directory to src/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 run-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 |
| -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 |
| |
| 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) |