"Fossies" - the Fresh Open Source Software Archive 
Member "apache-zookeeper-3.8.1/zookeeper-client/zookeeper-client-c/README" (25 Jan 2023, 7913 Bytes) of package /linux/misc/apache-zookeeper-3.8.1.tar.gz:
As a special service "Fossies" has tried to format the requested text file into HTML format (style:
standard) with prefixed line numbers.
Alternatively you can here
view or
download the uninterpreted source code file.
See also the last
Fossies "Diffs" side-by-side code changes report for "README":
3.6.2_vs_3.7.0.
1 Zookeeper C client library
2
3
4 This package provides a C client interface to Zookeeper server.
5
6 For the latest information about ZooKeeper, please visit our website at:
7 http://zookeeper.apache.org/
8 and our wiki, at:
9 https://cwiki.apache.org/confluence/display/ZOOKEEPER
10
11 Full documentation for this release can also be found in ../../docs/index.html
12
13
14 OVERVIEW
15
16 The client supports two types of APIs -- synchronous and asynchronous.
17
18 Asynchronous API provides non-blocking operations with completion callbacks and
19 relies on the application to implement event multiplexing on its behalf.
20
21 On the other hand, Synchronous API provides a blocking flavor of
22 zookeeper operations and runs its own event loop in a separate thread.
23
24 Sync and Async APIs can be mixed and matched within the same application.
25
26 The package includes two shared libraries: zookeeper_st and
27 zookeeper_mt. The former only provides the Async API and is not
28 thread-safe. The only reason this library exists is to support the
29 platforms were pthread library is not available or unstable
30 (i.e. FreeBSD 4.x). In all other cases the application developers are
31 advised to link against zookeeper_mt as it includes support for both
32 Sync and Async API.
33
34
35 INSTALLATION
36
37 If you're building the client from a source checkout you need to
38 follow the steps outlined below. If you're building from a release
39 tar downloaded from Apache please skip to step 2.
40
41 1) do a "ant compile_jute" from the zookeeper top level directory (.../trunk).
42 This will create a directory named "generated" under zookeeper-client/zookeeper-client-c.
43 Skip to step 3.
44 2) unzip/untar the source tarball and cd to the zookeeper-x.x.x/zookeeper-client/zookeeper-client-c directory
45 3) change directory to zookeeper-client/zookeeper-client-c and do a "autoreconf -if" to bootstrap
46 autoconf, automake and libtool. Please make sure you have autoconf
47 version 2.59 or greater installed. If cppunit is installed in a non-standard
48 directory, you need to specify where to find cppunit.m4. For example, if
49 cppunit is installed under /usr/local, run:
50
51 ACLOCAL="aclocal -I /usr/local/share/aclocal" autoreconf -if
52
53 4) do a "./configure [OPTIONS]" to generate the makefile. See INSTALL
54 for general information about running configure. Additionally, the
55 configure supports the following options:
56 --enable-debug enables optimization and enables debug info compiler
57 options, disabled by default
58 --without-syncapi disables Sync API support; zookeeper_mt library won't
59 be built, enabled by default
60 --disable-static do not build static libraries, enabled by default
61 --disable-shared do not build shared libraries, enabled by default
62 --without-cppunit do not build the test library, enabled by default.
63
64 5) do a "make" or "make install" to build the libraries and install them.
65 Alternatively, you can also build and run a unit test suite (and
66 you probably should). Please make sure you have cppunit-1.10.x or
67 higher installed before you execute step 4. Once ./configure has
68 finished, do a "make check". It will build the libraries, build
69 the tests and run them.
70 6) to generate doxygen documentation do a "make doxygen-doc". All
71 documentations will be placed to a new subfolder named docs. By
72 default only HTML documentation is generated. For information on
73 other document formats please use "./configure --help"
74
75 Alternatively you can use the CMake build system. On Windows, this is required.
76 Follow steps 1 and 2 above, and then continue here.
77
78 1) do a "cmake [OPTIONS]" to generate the makefile or msbuild files (the correct
79 build system will be generated based on your platform). Some options from above
80 are supported:
81 -DCMAKE_BUILD_TYPE Debug by default, Release enables optimzation etc.
82 -DWANT_SYNCAPI ON by default, OFF disables the Sync API support
83 -DWANT_CPPUNIT ON except on Windows, OFF disables the tests
84 -DWITH_OPENSSL ON by default, OFF disables the SSL support. You can also
85 specify a custom path by -DWITH_OPENSSL=/path/to/openssl/
86 -DWITH_CYRUS_SASL ON by default, OFF disables SASL support. You can also
87 specify a custom path by -DWITH_CYRUS_SASL=/path/to/cyrus-sasl/
88 -DBUILD_SHARED_LIBS not yet supported, only static libraries are built
89 other CMake options see "cmake --help" for generic options, such as generator
90
91 2) do a "cmake --build ." to build the default targets. Alternatively you can
92 invoke "make" or "msbuild" manually. If the tests were enabled, use "ctest -V"
93 to run them.
94
95 Current limitations of the CMake build system include lack of Solaris support,
96 no shared library option, no explicitly exported symbols (all are exported by
97 default), no versions on the libraries, and no documentation generation.
98 Features of CMake include a single, easily consumed cross-platform build system
99 to generate the ZooKeeper C Client libraries for any project, with little to no
100 configuration.
101
102 EXAMPLE/SAMPLE C CLIENT SHELL
103
104 NOTE: the ZooKeeper C client shell (cli_st and cli_mt) is meant as a
105 example/sample of ZooKeeper C client API usage. It is not a full
106 fledged client and not meant for production usage - see the Java
107 client shell for a fully featured shell.
108
109 You can test your client by running a zookeeper server (see
110 instructions on the project wiki page on how to run it) and connecting
111 to it using the zookeeper shell application cli that is built as part
112 of the installation procedure.
113
114 cli_mt (multithreaded, built against zookeeper_mt library) is shown in
115 this example, but you could also use cli_st (singlethreaded, built
116 against zookeeper_st library):
117
118 $ cli_mt zookeeper_host:9876
119
120 To start a client with read-only mode enabled, use the -r flag:
121
122 $ cli_mt -r zookeeper_host:9876
123
124 This is a client application that gives you a shell for executing
125 simple zookeeper commands. Once successfully started and connected to
126 the server it displays a shell prompt.
127
128 You can now enter zookeeper commands. For example, to create a node:
129
130 > create /my_new_node
131
132 To verify that the node's been created:
133
134 > ls /
135
136 You should see a list of nodes who are the children of the root node "/".
137
138 Here's a list of command supported by the cli shell:
139
140 ls <path> -- list children of a znode identified by <path>. The
141 command set a children watch on the znode.
142 get <path> -- get the value of a znode at <path>
143 set <path> <value> -- set the value of a znode at <path> to <value>
144 create [+e|+s] <path> -- create a znode as a child of znode <path>;
145 use +e option to create an ephemeral znode,
146 use +s option to create a znode with a sequence number
147 appended to the name. The operation will fail if
148 the parent znode (the one identified by <path>) doesn't
149 exist.
150 delete <path> -- delete the znode at <path>. The command will fail if the znode
151 has children.
152 sync <path> -- make sure all pending updates have been applied to znode at <path>
153 exists <path> -- returns a result code indicating whether the znode at <path>
154 exists. The command also sets a znode watch.
155 myid -- prints out the current zookeeper session id.
156 quit -- exit the shell.
157
158 In order to be able to use the zookeeper API in your application you have to
159 1) remember to include the zookeeper header
160 #include <zookeeper/zookeeper.h>
161 2) use -DTHREADED compiler option to enable Sync API; in this case you should
162 be linking your code against zookeeper_mt library
163
164 Please take a look at cli.c to understand how to use the two API types.
165 (TODO: some kind of short tutorial would be helpful, I guess)