ricsdl-package/examples/sync.py

   1 # Copyright (c) 2019 AT&T Intellectual Property.
   2 # Copyright (c) 2018-2019 Nokia.
   3 #
   4 # Licensed under the Apache License, Version 2.0 (the "License");
   5 # you may not use this file except in compliance with the License.
   6 # You may obtain a copy of the License at
   7 #
   8 #     http://www.apache.org/licenses/LICENSE-2.0
   9 #
  10 # Unless required by applicable law or agreed to in writing, software
  11 # distributed under the License is distributed on an "AS IS" BASIS,
  12 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13 # See the License for the specific language governing permissions and
  14 # limitations under the License.
  15
  16 #
  17 # This source code is part of the near-RT RIC (RAN Intelligent Controller)
  18 # platform project (RICP).
  19 #
  20
  21
  22 """
  23 Examples how to use synchronous API functions of the Shared Data Layer (SDL).
  24 Execution of  these examples requires:
  25  * Following Redis extension commands have been installed to runtime environment:
  26    - MSETPUB
  27    - SETIE
  28    - SETIEPUB
  29    - SETNXPUB
  30    - DELPUB
  31    - DELIE
  32    - DELIEPUB
  33    Redis v4.0 or greater is required. Older versions do not support extension modules.
  34    Implementation of above commands is produced by RIC DBaaS:
  35    https://gerrit.o-ran-sc.org/r/admin/repos/ric-plt/dbaas
  36    In official RIC deployments these commands are installed by `dbaas` service to Redis
  37    container(s).
  38    In development environment you may want install commands manually to pod/container, which is
  39    running Redis.
  40  * Following environment variables are needed to set to the pod/container where the application
  41    utilizing SDL is going to be run.
  42      DBAAS_SERVICE_HOST = [redis server address]
  43      DBAAS_SERVICE_PORT= [redis server port]
  44      DBAAS_MASTER_NAME = [master Redis sentinel name]. Needed to set only if sentinel is in use.
  45      DBAAS_SERVICE_SENTINEL_PORT = [Redis sentinel port number]. Needed to set only if sentinel
  46      is in use.
  47 """
  48 from ricsdl.syncstorage import SyncStorage
  49 from ricsdl.exceptions import RejectedByBackend, NotConnected, BackendError
  50
  51
  52 # Constants used in the examples below.
  53 MY_NS = 'my_ns'
  54 MY_GRP_NS = 'my_group_ns'
  55 MY_LOCK_NS = 'my_group_ns'
  56
  57
  58 def _try_func_return(func):
  59     """
  60     Generic wrapper function to call SDL API function and handle exceptions if they are raised.
  61     """
  62     try:
  63         return func()
  64     except RejectedByBackend as exp:
  65         print(f'SDL function {func.__name__} failed: {str(exp)}')
  66         # Permanent failure, just forward the exception
  67         raise
  68     except (NotConnected, BackendError) as exp:
  69         print(f'SDL function {func.__name__} failed for a temporal error: {str(exp)}')
  70         # Here we could have a retry logic
  71
  72
  73 # Creates SDL instance. The call creates connection to the SDL database backend.
  74 mysdl = _try_func_return(SyncStorage)
  75
  76
  77 # Sets a value 'my_value' for a key 'my_key' under given namespace. Note that value
  78 # type must be bytes and multiple key values can be set in one set function call.
  79 _try_func_return(lambda: mysdl.set(MY_NS, {'my_key': b'my_value'}))
  80
  81
  82 # Gets the value of 'my_value' under given namespace.
  83 # Note that the type of returned value is bytes.
  84 my_ret_dict = _try_func_return(lambda: mysdl.get(MY_NS, {'my_key', 'someting not existing'}))
  85 for key, val in my_ret_dict.items():
  86     assert val.decode("utf-8") == u'my_value'
  87
  88
  89 # Sets a value 'my_value2' for a key 'my_key' under given namespace only if the old value is
  90 # 'my_value'.
  91 # Note that value types must be bytes.
  92 was_set = _try_func_return(lambda: mysdl.set_if(MY_NS, 'my_key', b'my_value', b'my_value2'))
  93 assert was_set is True
  94 # Try again. This time value 'my_value2' won't be set, because the key has already 'my_value2'
  95 # value.
  96 was_set = _try_func_return(lambda: mysdl.set_if(MY_NS, 'my_key', b'my_value', b'my_value2'))
  97 assert was_set is False
  98
  99
 100 # Sets a value 'my_value' for a key 'my_key2' under given namespace only if the key doesn't exist.
 101 # Note that value types must be bytes.
 102 was_set = _try_func_return(lambda: mysdl.set_if_not_exists(MY_NS, 'my_key2', b'my_value'))
 103 assert was_set is True
 104 # Try again. This time the key 'my_key2' already exists.
 105 was_set = _try_func_return(lambda: mysdl.set_if_not_exists(MY_NS, 'my_key2', b'my_value'))
 106 assert was_set is False
 107
 108
 109 # Removes a key 'my_key' under given namespace.
 110 _try_func_return(lambda: mysdl.remove(MY_NS, 'my_key'))
 111 my_ret_dict = _try_func_return(lambda: mysdl.get(MY_NS, 'my_key'))
 112 assert my_ret_dict == {}
 113
 114
 115 # Removes a key 'my_key' under given namespace only if the old value is 'my_value'.
 116 was_removed = _try_func_return(lambda: mysdl.remove_if(MY_NS, 'my_key2', b'my_value'))
 117 assert was_removed is True
 118 # Try again to remove not anymore existing key 'my_key'.
 119 was_removed = _try_func_return(lambda: mysdl.remove_if(MY_NS, 'my_key2', b'my_value'))
 120 assert was_removed is False
 121
 122
 123 # Removes all the keys under given namespace.
 124 _try_func_return(lambda: mysdl.set(MY_NS, {'my_key': b'something'}))
 125 my_ret_dict = _try_func_return(lambda: mysdl.get(MY_NS, {'my_key'}))
 126 assert my_ret_dict != {}
 127
 128 _try_func_return(lambda: mysdl.remove_all(MY_NS))
 129 my_ret_dict = _try_func_return(lambda: mysdl.get(MY_NS, {'my_key'}))
 130 assert my_ret_dict == {}
 131
 132
 133 # Finds keys under given namespace that are matching to given key prefix 'my_k'.
 134 _try_func_return(lambda: mysdl.set(MY_NS, {'my_key': b'my_value'}))
 135 ret_keys = _try_func_return(lambda: mysdl.find_keys(MY_NS, 'my_k*'))
 136 assert ret_keys == ['my_key']
 137
 138
 139 # Finds keys and their values under given namespace that are matching to given key search
 140 # pattern 'my_k*'.
 141 # Note that the type of returned value is bytes.
 142 ret_key_values = _try_func_return(lambda: mysdl.find_and_get(MY_NS, 'my_k*'))
 143 assert ret_key_values == {'my_key': b'my_value'}
 144
 145 _try_func_return(lambda: mysdl.remove_all(MY_NS))
 146
 147
 148 # Adds a member 'a' to a group 'my_group' under given namespace. A group is a unique collection of
 149 # members.
 150 # Note that member type must be bytes and multiple members can be set in one set function call.
 151 _try_func_return(lambda: mysdl.add_member(MY_GRP_NS, 'my_group', {b'a'}))
 152 # Try again to add a member 'a'. This time 'a' won't be added, because 'a' belongs already to
 153 # the group.
 154 _try_func_return(lambda: mysdl.add_member(MY_GRP_NS, 'my_group', {b'a'}))
 155
 156
 157 # Gets group 'my_group' members under given namespace.
 158 # Note that the type of returned member is bytes.
 159 ret_members = _try_func_return(lambda: mysdl.get_members(MY_GRP_NS, 'my_group'))
 160 assert ret_members == {b'a'}
 161
 162
 163 # Checks if 'a' is a member of the group 'my_group' under given namespace.
 164 was_member = _try_func_return(lambda: mysdl.is_member(MY_GRP_NS, 'my_group', b'a'))
 165 assert was_member is True
 166 was_member = _try_func_return(lambda: mysdl.is_member(MY_GRP_NS, 'my_group', b'not a member'))
 167 assert was_member is False
 168
 169
 170 # Returns the count of members of a group 'my_group' under given namespace.
 171 ret_count = _try_func_return(lambda: mysdl.group_size(MY_GRP_NS, 'my_group'))
 172 assert ret_count == 1
 173
 174
 175 # Removes the member 'a' of the group 'my_group' under given namespace.
 176 _try_func_return(lambda: mysdl.remove_member(MY_GRP_NS, 'my_group', {b'a', b'not exists'}))
 177 ret_count = _try_func_return(lambda: mysdl.group_size(MY_GRP_NS, 'my_group'))
 178 assert ret_count == 0
 179
 180
 181 # Removes the group 'my_group' under given namespace.
 182 _try_func_return(lambda: mysdl.add_member(MY_GRP_NS, 'my_group', {b'a', b'b', b'c'}))
 183 ret_count = _try_func_return(lambda: mysdl.group_size(MY_GRP_NS, 'my_group'))
 184 assert ret_count == 3
 185
 186 _try_func_return(lambda: mysdl.remove_group(MY_GRP_NS, 'my_group'))
 187 ret_count = _try_func_return(lambda: mysdl.group_size(MY_GRP_NS, 'my_group'))
 188 ret_members = _try_func_return(lambda: mysdl.get_members(MY_GRP_NS, 'my_group'))
 189 assert ret_count == 0
 190 assert ret_members == set()
 191
 192
 193 # Gets a lock 'my_lock' resource under given namespace.
 194 # Note that this function does not take a lock, you need to call 'acquire' function to take
 195 # the lock to yourself.
 196 my_lock = _try_func_return(lambda: mysdl.get_lock_resource(MY_LOCK_NS, "my_lock", expiration=5.5))
 197 assert my_lock is not None
 198
 199
 200 # Acquires a lock from the lock resource. Return True if lock was taken within given retry limits.
 201 was_acquired = _try_func_return(lambda: my_lock.acquire(retry_interval=0.5, retry_timeout=2))
 202 assert was_acquired is True
 203 # Try again. This time a lock won't be acquired successfully, because we have a lock already.
 204 was_acquired = _try_func_return(lambda: my_lock.acquire(retry_interval=0.1, retry_timeout=0.2))
 205 assert was_acquired is False
 206
 207
 208 # Refreshs the remaining validity time of the existing lock back to the initial value.
 209 _try_func_return(my_lock.refresh)
 210
 211
 212 # Gets the remaining validity time of the lock.
 213 ret_time = _try_func_return(my_lock.get_validity_time)
 214 assert ret_time != 0
 215
 216
 217 # Releases the lock.
 218 _try_func_return(my_lock.release)
 219
 220
 221 # Locking example what utilizes python 'with' statement with SDL lock.
 222 # The lock is released automatically when we are out of the scope of
 223 # 'the with my_lock' statement.
 224 my_lock = _try_func_return(lambda: mysdl.get_lock_resource(MY_LOCK_NS, "my_lock", 2.5))
 225 with my_lock:
 226     # Just an example how to use lock API
 227     time_left = _try_func_return(my_lock.get_validity_time)
 228
 229     # Add here operations what needs to be done under a lock, for example some
 230     # operations with a shared resources what needs to be done in a mutually
 231     # exclusive way.
 232
 233 # Lock is not anymore hold here
 234
 235
 236 # Closes the SDL connection.
 237 mysdl.close()