|
7 | 7 | <headerFileName>DistributedLockWrappers.h</headerFileName> |
8 | 8 | <functions> |
9 | 9 | <function> |
10 | | - <description>Create a new lock with a given name or get it if |
11 | | - it already exists. Return the lock handle.</description> |
| 10 | + <description>Create a new distributed lock with a given name or get it if it already exists. |
| 11 | +@param name the name of the lock to create or retrieve |
| 12 | +@param err a mutable variable that will retain the error code in event of a problem. On failure, **err** is assigned a non-zero value. |
| 13 | +@return 0 on error, or the id of the lock otherwise. This id can then be used as a parameter to other lock related functions. |
| 14 | + |
| 15 | + |
| 16 | + mutable uint64 lock_id = 0ul; |
| 17 | + mutable uint64 err = 0ul; |
| 18 | + lock_id = dlCreateOrGetLock("My Sentinel Lock1", err); |
| 19 | + if (err != 0ul) { |
| 20 | + printStringLn("Error in creating My Sentinel Lock1. rc = " + |
| 21 | + (rstring)dlGetLastDistributedLockErrorCode() + ", msg = " + dlGetLastDistributedLockErrorString()); |
| 22 | + } else { |
| 23 | + printStringLn("My Sentinel Lock1 was created with an id of " + (rstring)lock_id); |
| 24 | + } |
| 25 | + |
| 26 | + </description> |
12 | 27 | <prototype><![CDATA[ public stateful uint64 dlCreateOrGetLock(rstring name, mutable uint64 err) ]]></prototype> |
13 | 28 | </function> |
14 | 29 | <function> |
15 | | - <description>Remove lock. Return the true if the lock was there.</description> |
| 30 | + <description>Remove the distributed lock with the given id. |
| 31 | +**NOTE**: Since the whole purpose of distributed locks is to ensure operations are performed safely on shared resources by multiple unrelated application components, do not remove distributed locks abruptly unless you are very clear about what you are doing. |
| 32 | +Do it only when you are sure that no one is using the lock at the time of removing it. |
| 33 | +@param lock the id of the lock to remove. |
| 34 | +@param err a mutable variable to receive the error code. |
| 35 | +@return 'true' on success, 'false' otherwise. In the case of an error, a non-zero value is assigned to the **err** variable. |
| 36 | + |
| 37 | + |
| 38 | + |
| 39 | + mutable uint64 lock_id = 0ul; |
| 40 | + mutable uint64 err = 0ul; |
| 41 | + lock_id = dlCreateOrGetLock("My Sentinel Lock1", err); |
| 42 | + ... |
| 43 | + err = 0ul; |
| 44 | + boolean myResult = dlRemoveLock(lock_id, err); |
| 45 | + if (!myResult) { |
| 46 | + printStringLn("Failed to remove the lock My Sentinel Lock1 lock_id=" +(rstring)lock_id + ", err=" + (rstring)err + ", msg=" + dlGetLastDistributedLockErrorString()); |
| 47 | + } else { |
| 48 | + printStringLn("We removed the lock My Sentinel Lock1 lock_id =" + (rstring)lock_id); |
| 49 | + } |
| 50 | + </description> |
16 | 51 | <prototype><![CDATA[ public stateful boolean dlRemoveLock(uint64 lock, mutable uint64 err) ]]></prototype> |
17 | 52 | </function> |
18 | 53 | <function> |
19 | | - <description>Acquire lock.</description> |
20 | | - <prototype><![CDATA[ public stateful void dlAcquireLock(uint64 lock, mutable uint64 err) ]]></prototype> |
| 54 | + <description> This function can be called to acquire a distributed lock. Acquiring a lock before performing a write/delete operation into a data store that is shared by multiple applications is a good way to ensure safe access of the shared resource. This function can be used to acquire such a lock before in order to gain exclusive access for a shared resource. Locks acquired through this function will be owned until the lock is released via [dlReleaseLock(uint64,uint64)]. |
| 55 | + |
| 56 | +**IMPORTANT NOTE:** |
| 57 | +Once called, this function could spin loop for a very long time (three or four minutes) until it acquires the distributed lock or it times out due to the distributed lock being not yet available. Another important factor is that once the lock is granted, it is given to you for an infinite period of time. Hence, it is your responsibility to properly release the lock at the end of your task. There is no external mechanism to take the lock back from you in case your code crashes after acquiring the lock. |
| 58 | +An alternative overloaded function is available that allows you to specify a maximum time to wait, and also allows lock ownership to expire after a given amount of time. This alternative function is also called [dlAcquireLock(uint64, float64, float64, uint64 ) |dlAcquireLock]. |
| 59 | +@param lock the id of the lock to acquire. |
| 60 | +@param err a mutable variable to receive a non-zero error code in the event of a problem acquiring the lock. Will be set to '0' on success. |
| 61 | + |
| 62 | + |
| 63 | + mutable uint64 lk = 0ul; |
| 64 | + mutable uint64 err = 0ul; |
| 65 | + lk = dlCreateOrGetLock("My Sentinel Lock1", err); |
| 66 | + //do error checking |
| 67 | + |
| 68 | + dlAcquireLock(lk, err); |
| 69 | + if (err == 0ul) { |
| 70 | + printStringLn("We acquired the lock My Sentinel Lock1 lk=" + (rstring)lk); |
| 71 | + //perform operation |
| 72 | + |
| 73 | + //call dlReleaseLock once done |
| 74 | + } else { |
| 75 | + printStringLn("Failed to acquire the lock My Sentinel Lock1 lk=" + (rstring)lk + |
| 76 | + " rc = " + (rstring)dlGetLastDistributedLockErrorCode() + |
| 77 | + ", msg = " + dlGetLastDistributedLockErrorString()); |
| 78 | + // It is advisable to return from here since the lock is not granted. |
| 79 | + return; |
| 80 | + } |
| 81 | + |
| 82 | +</description> |
| 83 | + <prototype><![CDATA[ public stateful void dlAcquireLock(uint64 lock, mutable uint64 err) ]]></prototype> |
21 | 84 | </function> |
22 | 85 | <function> |
23 | | - <description>Acquire lock, with an explicit lease time in seconds.</description> |
| 86 | + <description>Acquire lock, with an explicit lease time in seconds and a maximum time to wait to acquire the lock. |
| 87 | +This overloaded function can be used to acquire a given distributed lock id. This function has two advantages over the other [dlAcquireLock(uint64, uint64)|dlAcquireLock] function. |
| 88 | +First of all, callers can pass a fixed lease time for the lock, indicating that the lock will be needed at most for a specified period before which the caller will relinquish this lock. |
| 89 | +In addition, the caller can also specify how long the caller is willing to wait to acquire the lock. |
| 90 | +@param lock the id of the lock to acquire, must have been previously created. |
| 91 | +@param leaseTime the length of time, in seconds, for which the lock is needed. Must be greater than 0. If the lock is not released after the requested lease time due to a program crash or a programmatic error, the lock will be automatically released and made available for others to acquire. |
| 92 | +@param maxWaitTimeToAcquireLock Maximum time to wait to acquire the lock, in seconds. If the lock acquisition is not done within the specified max wait time, this function will exit with an error instead of spin looping forever. |
| 93 | +@param err a mutable variable to receive a non-zero error code in the event of a problem acquiring the lock. Will be set to '0' on success. |
| 94 | + </description> |
24 | 95 | <prototype><![CDATA[ public stateful void dlAcquireLock(uint64 lock, float64 leaseTime, float64 maxWaitTimeToAcquireLock, mutable uint64 err) ]]></prototype> |
25 | 96 | </function> |
26 | 97 | <function> |
27 | | - <description>Release lock.</description> |
| 98 | + <description>Release the given distributed lock id. |
| 99 | +@param lock the id of the lock to release. The specified lock will be made available for other callers to acquire. |
| 100 | +@param err a mutable variable to receive a non-zero error code in the event of a problem releasing the lock. Will be set to '0' on success. |
| 101 | + |
| 102 | +</description> |
28 | 103 | <prototype><![CDATA[ public stateful void dlReleaseLock(uint64 lock, mutable uint64 err) ]]></prototype> |
29 | 104 | </function> |
30 | 105 | <function> |
31 | | - <description>Get the process id that is currently holding a given lock.</description> |
| 106 | + <description>Get the process id that is currently holding a given lock. This function can be used for test, diagnostic or informational purposes. |
| 107 | +@param name the name of the distributed lock in question. |
| 108 | +@param err stores the error code if an error occurs, or '0' otherwise. |
| 109 | +@return the id of the Linux process id of the processing element (PE) that currently owns the lock, or '0' if no one owns the lock. |
| 110 | + |
| 111 | + mutable uint32 pid = dlGetPidForLock("file_lock", err); |
| 112 | + if (err != 0ul) { |
| 113 | + rstring msg = dlGetLastDistributedLockErrorString(); |
| 114 | + uint64 rc = dlGetLastDistributedLockErrorCode(); |
| 115 | + printStringLn("Error in dlGetPidForLock(file_lock) rc = " + (rstring)(rc) + ", msg =" + msg ); |
| 116 | + } else { |
| 117 | + printStringLn("Before lock acquisition: pid owning the file_lock = " + (rstring)pid); |
| 118 | + } |
| 119 | +</description> |
32 | 120 | <prototype><![CDATA[ public stateful uint32 dlGetPidForLock(rstring name, mutable uint64 err) ]]></prototype> |
33 | 121 | </function> |
34 | 122 | <function> |
35 | | - <description>Get the description of the last DB error.</description> |
| 123 | + <description>Get the description of the error that occurred on the most recently executed operation in the DL API, if any. |
| 124 | +@return a message describing the error that occurred, or the empty string if the last DL operation was successful.</description> |
36 | 125 | <prototype><![CDATA[ public stateful rstring dlGetLastDistributedLockErrorString() ]]></prototype> |
37 | 126 | </function> |
38 | 127 | <function> |
39 | | - <description>Get the error code of the last DB error.</description> |
| 128 | + <description>Get the error code of the last DL error |
| 129 | +@return the error code for the most recently executed operation, or '0' if no error occurred. .</description> |
40 | 130 | <prototype><![CDATA[ public stateful uint64 dlGetLastDistributedLockErrorCode() ]]></prototype> |
41 | 131 | </function> |
42 | 132 | </functions> |
|
46 | 136 | <cmn:managedLibrary> |
47 | 137 | <cmn:lib>DistributedProcessStoreLib</cmn:lib> |
48 | 138 | <cmn:lib>memcached</cmn:lib> |
49 | | - <cmn:lib>sds</cmn:lib> |
| 139 | + <!-- <cmn:lib>sds</cmn:lib> --> |
50 | 140 | <cmn:lib>hiredis</cmn:lib> |
51 | 141 | <cmn:lib>uv</cmn:lib> |
52 | 142 | <cmn:lib>crypto</cmn:lib> |
53 | 143 | <cmn:lib>ssl</cmn:lib> |
| 144 | + <cmn:lib>ldap_r</cmn:lib> |
54 | 145 | <cmn:lib>cassandra</cmn:lib> |
55 | 146 | <cmn:lib>curl</cmn:lib> |
56 | 147 | <cmn:lib>json-c</cmn:lib> |
57 | 148 | <cmn:lib>bson</cmn:lib> |
58 | 149 | <cmn:lib>mongoc</cmn:lib> |
59 | | - <cmn:lib>couchbase</cmn:lib> |
60 | | - <cmn:lib>lua</cmn:lib> |
61 | | - <cmn:lib>aerospike</cmn:lib> |
| 150 | + <!-- <cmn:lib>couchbase</cmn:lib> --> |
| 151 | + <!-- <cmn:lib>aerospike</cmn:lib> --> |
62 | 152 | <cmn:command>../../../../impl/bin/archLevel</cmn:command> |
63 | 153 | </cmn:managedLibrary> |
64 | 154 | </library> |
|
0 commit comments