Apache Mesos
zookeeper.hpp
Go to the documentation of this file.
1 // Licensed to the Apache Software Foundation (ASF) under one
2 // or more contributor license agreements. See the NOTICE file
3 // distributed with this work for additional information
4 // regarding copyright ownership. The ASF licenses this file
5 // to you under the Apache License, Version 2.0 (the
6 // "License"); you may not use this file except in compliance
7 // with the License. You may obtain a copy of the License at
8 //
9 // http://www.apache.org/licenses/LICENSE-2.0
10 //
11 // Unless required by applicable law or agreed to in writing, software
12 // distributed under the License is distributed on an "AS IS" BASIS,
13 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 // See the License for the specific language governing permissions and
15 // limitations under the License.
16 
24 #ifndef __MESOS_ZOOKEEPER_HPP__
25 #define __MESOS_ZOOKEEPER_HPP__
26 
27 #include <stdint.h>
28 
29 #include <zookeeper.h>
30 
31 #ifdef __WINDOWS__
32 // NOTE: We need to undefine this macro to prevent it from bleeding
33 // into our code and thereby break compilation of our namespaced ACLs.
34 // This macro is defined in zookeeper/src/c/include/winconfig.h.
35 #undef ACL
36 #endif // __WINDOWS__
37 
38 #include <string>
39 #include <vector>
40 
41 #include <stout/duration.hpp>
42 
43 
44 /* Forward declarations of classes we are using. */
45 class ZooKeeper;
46 class ZooKeeperProcess;
47 
59 class Watcher
60 {
61 public:
62  virtual void process(
63  int type,
64  int state,
65  int64_t sessionId,
66  const std::string& path) = 0;
67 
68  virtual ~Watcher() {}
69 };
70 
71 
72 /*
73  * TODO(benh): Clean up this documentation.
74  *
75  * This is the main class of ZooKeeper client library. To use a
76  * ZooKeeper service, an application must first instantiate an object
77  * of ZooKeeper class. All the iterations will be done by calling the
78  * methods of ZooKeeper class.
79  *
80  * Once a connection to a server is established, a session ID is
81  * assigned to the client. The client will send heart beats to the
82  * server periodically to keep the session valid.
83  *
84  * The application can call ZooKeeper APIs through a client as long as
85  * the session ID of the client remains valid.
86  *
87  * If for some reason, the client fails to send heart beats to the
88  * server for a prolonged period of time (exceeding the sessionTimeout
89  * value, for instance), the server will expire the session, and the
90  * session ID will become invalid. The client object will no longer be
91  * usable. To make ZooKeeper API calls, the application must create a
92  * new client object.
93  *
94  * If the ZooKeeper server the client currently connects to fails or
95  * otherwise does not respond, the client will automatically try to
96  * connect to another server before its session ID expires. If
97  * successful, the application can continue to use the client.
98  *
99  * Some successful ZooKeeper API calls can leave watches on the "data
100  * nodes" in the ZooKeeper server. Other successful ZooKeeper API
101  * calls can trigger those watches. Once a watch is triggered, an
102  * event will be delivered to the client which left the watch at the
103  * first place. Each watch can be triggered only once. Thus, up to one
104  * event will be delivered to a client for every watch it leaves.
105  *
106  * A client needs an object of a class implementing Watcher interface
107  * for processing the events delivered to the client. When a client
108  * drops current connection and re-connects to a server, all the
109  * existing watches are considered as being triggered but the
110  * undelivered events are lost. To emulate this, the client will
111  * generate a special event to tell the event handler a connection has
112  * been dropped. This special event has type EventNone and state
113  * sKeeperStateDisconnected.
114  */
116 {
117 public:
131  ZooKeeper(const std::string& servers,
132  const Duration& sessionTimeout,
133  Watcher* watcher);
134 
135  ~ZooKeeper();
136 
142  int getState();
143 
149  int64_t getSessionId();
150 
159  Duration getSessionTimeout() const;
160 
164  int authenticate(const std::string& scheme, const std::string& credentials);
165 
200  int create(
201  const std::string& path,
202  const std::string& data,
203  const ACL_vector& acl,
204  int flags,
205  std::string* result,
206  bool recursive = false);
207 
227  int remove(const std::string& path, int version);
228 
247  int exists(const std::string& path, bool watch, Stat* stat);
248 
267  int get(
268  const std::string& path,
269  bool watch,
270  std::string* result,
271  Stat* stat);
272 
289  int getChildren(
290  const std::string& path,
291  bool watch,
292  std::vector<std::string>* results);
293 
312  int set(const std::string& path, const std::string& data, int version);
313 
319  std::string message(int code) const;
320 
328  bool retryable(int code);
329 
330 
331 protected:
332  /* Underlying implementation (pimpl idiom). */
333  ZooKeeperProcess* process;
334 
335 private:
336  /* ZooKeeper instances are not copyable. */
337  ZooKeeper(const ZooKeeper& that);
338  ZooKeeper& operator=(const ZooKeeper& that);
339 };
340 
341 
342 #endif /* __MESOS_ZOOKEEPER_HPP__ */
Definition: path.hpp:29
Definition: zookeeper.hpp:115
virtual ~Watcher()
Definition: zookeeper.hpp:68
ZooKeeperProcess * process
Definition: zookeeper.hpp:333
Definition: duration.hpp:32
This interface specifies the public interface an event handler class must implement.
Definition: zookeeper.hpp:59
process::Future< Version > version()
Definition: version.hpp:32
Try< hashmap< std::string, uint64_t > > stat(const std::string &hierarchy, const std::string &cgroup, const std::string &file)
virtual void process(int type, int state, int64_t sessionId, const std::string &path)=0
Try< uint32_t > type(const std::string &path)
Try< Nothing > create(const std::string &hierarchy, const std::string &cgroup, bool recursive=false)
bool exists(const std::string &hierarchy, const std::string &cgroup)
Definition: parse.hpp:33