1 /**
2  * Licensed to the Apache Software Foundation (ASF) under one
3  * or more contributor license agreements.  See the NOTICE file
4  * distributed with this work for additional information
5  * regarding copyright ownership.  The ASF licenses this file
6  * to you under the Apache License, Version 2.0 (the
7  * "License"); you may not use this file except in compliance
8  * with the License.  You may obtain a copy of the License at
9  *
10  *     http://www.apache.org/licenses/LICENSE-2.0
11  *
12  * Unless required by applicable law or agreed to in writing, software
13  * distributed under the License is distributed on an "AS IS" BASIS,
14  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15  * See the License for the specific language governing permissions and
16  * limitations under the License.
17  */
18 #ifndef ZOOKEEPER_LOCK_H_
19 #define ZOOKEEPER_LOCK_H_
20 
21 #include <zookeeper.h>
22 #include <pthread.h>
23 
24 #ifdef __cplusplus
25 extern "C" {
26 #endif
27 /**
28  * \brief the call back function called on status change of lock
29  *
30  * the call back funtion is called with a rc of 0 if lock is acquired and
31  * with an rc of 1 if the lock is released
32  * \param rc the value to let us know if its locked or unlocked
33  * \param cbdata the callback data that we passed when initializing
34  * the zookeeper lock.
35  */
36 
37 typedef void (* zkr_lock_completion) (int rc, void* cbdata);
38 
39 /**
40  * \file zoo_lock.h
41  * \brief zookeeper recipe for locking and leader election.
42  * this api implements a writelock on a given path in zookeeper.
43  * this api can also be used for leader election.
44  */
45 
46 struct zkr_lock_mutex {
47     zhandle_t *zh;
48     char *path;
49     struct ACL_vector *acl;
50     char *id;
51     void *cbdata;
52     zkr_lock_completion completion;
53     pthread_mutex_t pmutex;
54     int isOwner;
55     char* ownerid;
56 };
57 
58 typedef struct zkr_lock_mutex zkr_lock_mutex_t;
59 
60 
61 /**
62  * \brief initializing a zookeeper lock.
63  *
64  * this method instantiates the zookeeper mutex lock.
65  * \param mutex the mutex to initialize
66  * \param zh the zookeeper handle to use
67  * \param path the path in zookeeper to use for locking
68  * \param acl the acls to use in zookeeper.
69  * \return return 0 if successful.
70  */
71 ZOOAPI int zkr_lock_init(zkr_lock_mutex_t *mutex, zhandle_t* zh,
72                       char* path, struct ACL_vector *acl);
73 
74 /**
75  * \brief initializing a zookeeper lock.
76  *
77  *
78  * this method instantiates the zookeeper mutex lock with
79  * a completion function.
80  *
81  * \param mutex the mutex to initialize
82  * \param zh the zookeeper handle to use
83  * \param path the path in zookeeper to use for locking
84  * \param acl the acls to use in zookeeper.
85  * \param completion the callback thats called when lock
86  * is acquired and released.
87  * \param cbdata the callback method is called with data
88  * \return return 0 if successful.
89  */
90 ZOOAPI int zkr_lock_init_cb(zkr_lock_mutex_t *mutex, zhandle_t* zh,
91                       char* path, struct ACL_vector *acl,
92                       zkr_lock_completion completion, void* cbdata);
93 
94 /**
95  * \brief lock the zookeeper mutex
96  *
97  * this method tries locking the mutex
98  * \param mutex the zookeeper mutex
99  * \return return 0 if there is no error. check
100  * with zkr_lock_isowner() if you have the lock
101  */
102 ZOOAPI int zkr_lock_lock(zkr_lock_mutex_t *mutex);
103 
104 /**
105  * \brief unlock the zookeeper mutex
106  *
107  * this method unlocks the zookeeper mutex
108  * \param mutex the zookeeper mutex
109  * \return return 0 if there is not error in executing unlock.
110  * else returns non zero
111  */
112 ZOOAPI int zkr_lock_unlock(zkr_lock_mutex_t *mutex);
113 
114 /**
115  * \brief set the callback function for zookeeper mutex
116  *
117  * this method sets the callback for zookeeper mutex
118  * \param mutex the zookeeper mutex
119  * \param callback the call back completion function
120  */
121 ZOOAPI void zkr_lock_setcallback(zkr_lock_mutex_t *mutex,
122                            zkr_lock_completion completion);
123 
124 /**
125  * \brief get the callback function for zookeeper mutex
126  *
127  * this method gets the callback funtion for zookeeper mutex
128  * \param mutex the zookeeper mutex
129  * \return the lock completion function
130  */
131 ZOOAPI zkr_lock_completion zkr_lock_getcallback(zkr_lock_mutex_t *mutex);
132 
133 /**
134  * \brief destroy the mutex
135  * this method free the mutex
136  * \param mutex destroy the zookepeer lock.
137  * \return return 0 if destroyed.
138  */
139 ZOOAPI int zkr_lock_destroy(zkr_lock_mutex_t* mutex);
140 
141 /**
142  * \brief return the parent path this mutex is using
143  * this method returns the parent path
144  * \param mutex the mutex
145  * \return return the parent path
146  */
147 ZOOAPI char* zkr_lock_getpath(zkr_lock_mutex_t *mutex);
148 
149 /**
150  * \brief return if this mutex is owner of the lock
151  * this method returns if its owner or not
152  * \param mutex the mutex
153  * \return return true if is owner and false if not
154  */
155 ZOOAPI int zkr_lock_isowner(zkr_lock_mutex_t *mutex);
156 
157 /**
158  * \brief return the id for this mutex
159  * this mutex retunrns the id string
160  * \param mutex the mutex
161  * \return the id for this mutex
162  */
163 ZOOAPI char* zkr_lock_getid(zkr_lock_mutex_t *mutex);
164 
165 #ifdef __cplusplus
166 }
167 #endif
168 #endif  //ZOOKEEPER_LOCK_H_
169