# See the License for the specific language governing permissions and
# limitations under the License.
-"""The module provides synchronous shareddatalayer interface."""
+#
+# This source code is part of the near-RT RIC (RAN Intelligent Controller)
+# platform project (RICP).
+#
+
+
+"""The module provides synchronous Shared Data Layer (SDL) interface."""
from typing import (Dict, Set, List, Union)
from abc import ABC, abstractmethod
-
+from ricsdl.exceptions import (
+ RejectedByBackend
+)
__all__ = [
'SyncStorageAbc',
class SyncLockAbc(ABC):
"""
- An abstract synchronous lock class providing a shared, distributed locking mechanism, which can
- be utilized by clients to be able to operate with a shared resource in a mutually exclusive way.
+ An abstract synchronous Shared Data Layer (SDL) lock class providing a shared, distributed
+ locking mechanism, which can be utilized by clients to be able to operate with a shared
+ resource in a mutually exclusive way.
A lock instance is created per namespace and it is identified by its `name` within a
namespace.
Args:
ns (str): Namespace under which this lock is targeted.
- name (str): Lock name, identifies the lock key in shared data layer storage.
+ name (str): Lock name, identifies the lock key in SDL storage.
expiration (int, float): Lock expiration time after which the lock is removed if it hasn't
been released earlier by a 'release' method.
self._expiration = expiration
def __enter__(self, *args, **kwargs):
- self.acquire(*args, **kwargs)
- return self
+ if self.acquire(*args, **kwargs):
+ return self
+ raise RejectedByBackend("Unable to acquire lock within the time specified")
def __exit__(self, exception_type, exception_value, traceback):
self.release()
A lock can be used as a mutual exclusion locking entry for a shared resources.
All the exceptions except SdlTypeError are derived from SdlException base class. Client
- can catch only that exception if separate handling for different shareddatalayer error
- situations is not needed. Exception SdlTypeError is derived from build-in TypeError and it
- indicates misuse of the SDL API.
+ can catch only that exception if separate handling for different SDL error situations is
+ not needed. Exception SdlTypeError is derived from build-in TypeError and it indicates
+ misuse of the SDL API.
Args:
retry_interval (int, float): Lock acquiring retry interval in seconds. Supports both
Raises:
SdlTypeError: If function's argument is of an inappropriate type.
- NotConnected: If shareddatalayer is not connected to the backend data storage.
+ NotConnected: If SDL is not connected to the backend data storage.
RejectedByBackend: If backend data storage rejects the request.
BackendError: If the backend data storage fails to process the request.
"""
pass
-
def release(self) -> None:
"""
Release a lock atomically.
Release the already acquired lock.
Exceptions thrown are all derived from SdlException base class. Client can catch only that
- exception if separate handling for different shareddatalayer error situations is not
- needed.
+ exception if separate handling for different SDL error situations is not needed.
Args:
None
None
Raises:
- NotConnected: If shareddatalayer is not connected to the backend data storage.
+ NotConnected: If SDL is not connected to the backend data storage.
RejectedByBackend: If backend data storage rejects the request.
BackendError: If the backend data storage fails to process the request.
"""
pass
-
def refresh(self) -> None:
"""
Refresh the remaining validity time of the existing lock back to an initial value.
Exceptions thrown are all derived from SdlException base class. Client can catch only that
- exception if separate handling for different shareddatalayer error situations is not
- needed.
+ exception if separate handling for different SDL error situations is not needed.
Args:
None
None
Raises:
- NotConnected: If shareddatalayer is not connected to the backend data storage.
+ NotConnected: If SDL is not connected to the backend data storage.
RejectedByBackend: If backend data storage rejects the request.
BackendError: If the backend data storage fails to process the request.
"""
pass
-
def get_validity_time(self) -> Union[int, float]:
"""
Get atomically the remaining validity time of the lock in seconds.
Return atomically time in seconds until the lock expires.
Exceptions thrown are all derived from SdlException base class. Client can catch only that
- exception if separate handling for different shareddatalayer error situations is not
- needed.
+ exception if separate handling for different SDL error situations is not needed.
Args:
None
(int, float): Validity time of the lock in seconds.
Raises:
- NotConnected: If shareddatalayer is not connected to the backend data storage.
+ NotConnected: If SDL is not connected to the backend data storage.
RejectedByBackend: If backend data storage rejects the request.
BackendError: If the backend data storage fails to process the request.
"""
class SyncStorageAbc(ABC):
"""
- An abstract class providing synchronous access to shared data layer storage.
+ An abstract class providing synchronous access to Shared Data Layer (SDL) storage.
- This class provides synchronous access to all the namespaces in shared data layer storage.
+ This class provides synchronous access to all the namespaces in SDL storage.
Data can be written, read and removed based on keys known to clients. Keys are unique within
a namespace, namespace identifier is passed as a parameter to all the operations.
A concrete implementation subclass 'SyncStorage' derives from this abstract class.
"""
+ @abstractmethod
+ def close(self):
+ """
+ Close the connection to SDL storage.
+
+ Args:
+ None
+
+ Returns:
+ None
+
+ Raises:
+ NotConnected: If SDL is not connected to the backend data storage.
+ RejectedByBackend: If backend data storage rejects the request.
+ BackendError: If the backend data storage fails to process the request.
+ """
+ pass
+
@abstractmethod
def set(self, ns: str, data_map: Dict[str, bytes]) -> None:
"""
- Write data to shared data layer storage.
+ Write data to SDL storage.
Writing is done atomically, i.e. either all succeeds, or all fails.
All the exceptions except SdlTypeError are derived from SdlException base class. Client
- can catch only that exception if separate handling for different shareddatalayer error
- situations is not needed. Exception SdlTypeError is derived from build-in TypeError and it
- indicates misuse of the SDL API.
+ can catch only that exception if separate handling for different SDL error situations is
+ not needed. Exception SdlTypeError is derived from build-in TypeError and it indicates
+ misuse of the SDL API.
Args:
ns (str): Namespace under which this operation is targeted.
Raises:
SdlTypeError: If function's argument is of an inappropriate type.
- NotConnected: If shareddatalayer is not connected to the backend data storage.
+ NotConnected: If SDL is not connected to the backend data storage.
RejectedByBackend: If backend data storage rejects the request.
BackendError: If the backend data storage fails to process the request.
"""
pass
-
@abstractmethod
def set_if(self, ns: str, key: str, old_data: bytes, new_data: bytes) -> bool:
"""
user's last known value.
All the exceptions except SdlTypeError are derived from SdlException base class. Client
- can catch only that exception if separate handling for different shareddatalayer error
- situations is not needed. Exception SdlTypeError is derived from build-in TypeError and it
- indicates misuse of the SDL API.
+ can catch only that exception if separate handling for different SDL error situations is
+ not needed. Exception SdlTypeError is derived from build-in TypeError and it indicates
+ misuse of the SDL API.
Args:
ns (str): Namespace under which this operation is targeted.
Raises:
SdlTypeError: If function's argument is of an inappropriate type.
- NotConnected: If shareddatalayer is not connected to the backend data storage.
+ NotConnected: If SDL is not connected to the backend data storage.
RejectedByBackend: If backend data storage rejects the request.
BackendError: If the backend data storage fails to process the request.
"""
pass
-
@abstractmethod
def set_if_not_exists(self, ns: str, key: str, data: bytes) -> bool:
"""
- Write data to shared data layer storage if key does not exist.
+ Write data to SDL storage if key does not exist.
Conditionally set the value of a key. If key already exists, then its value is not
modified. Checking the key existence and potential set operation is done as a one atomic
operation.
All the exceptions except SdlTypeError are derived from SdlException base class. Client
- can catch only that exception if separate handling for different shareddatalayer error
- situations is not needed. Exception SdlTypeError is derived from build-in TypeError and it
- indicates misuse of the SDL API.
+ can catch only that exception if separate handling for different SDL error situations is
+ not needed. Exception SdlTypeError is derived from build-in TypeError and it indicates
+ misuse of the SDL API.
Args:
ns (str): Namespace under which this operation is targeted.
Raises:
SdlTypeError: If function's argument is of an inappropriate type.
- NotConnected: If shareddatalayer is not connected to the backend data storage.
+ NotConnected: If SDL is not connected to the backend data storage.
RejectedByBackend: If backend data storage rejects the request.
BackendError: If the backend data storage fails to process the request.
"""
pass
-
@abstractmethod
def get(self, ns: str, keys: Union[str, Set[str]]) -> Dict[str, bytes]:
"""
- Read data from shared data layer storage.
+ Read data from SDL storage.
Only those entries that are found will be returned.
All the exceptions except SdlTypeError are derived from SdlException base class. Client
- can catch only that exception if separate handling for different shareddatalayer error
- situations is not needed. Exception SdlTypeError is derived from build-in TypeError and it
- indicates misuse of the SDL API.
+ can catch only that exception if separate handling for different SDL error situations is
+ not needed. Exception SdlTypeError is derived from build-in TypeError and it indicates
+ misuse of the SDL API.
Args:
ns (str): Namespace under which this operation is targeted.
Raises:
SdlTypeError: If function's argument is of an inappropriate type.
- NotConnected: If shareddatalayer is not connected to the backend data storage.
+ NotConnected: If SDL is not connected to the backend data storage.
RejectedByBackend: If backend data storage rejects the request.
BackendError: If the backend data storage fails to process the request.
"""
pass
-
@abstractmethod
def find_keys(self, ns: str, key_prefix: str) -> List[str]:
"""
No prior knowledge about the keys in the given namespace exists, thus operation is not
guaranteed to be atomic or isolated.
All the exceptions except SdlTypeError are derived from SdlException base class. Client
- can catch only that exception if separate handling for different shareddatalayer error
- situations is not needed. Exception SdlTypeError is derived from build-in TypeError and it
- indicates misuse of the SDL API.
+ can catch only that exception if separate handling for different SDL error situations is
+ not needed. Exception SdlTypeError is derived from build-in TypeError and it indicates
+ misuse of the SDL API.
Args:
ns (str): Namespace under which this operation is targeted.
Raises:
SdlTypeError: If function's argument is of an inappropriate type.
- NotConnected: If shareddatalayer is not connected to the backend data storage.
+ NotConnected: If SDL is not connected to the backend data storage.
RejectedByBackend: If backend data storage rejects the request.
BackendError: If the backend data storage fails to process the request.
"""
pass
-
@abstractmethod
def find_and_get(self, ns: str, key_prefix: str, atomic: bool) -> Dict[str, bytes]:
"""
- Find keys and get their respective data from shared data layer storage.
+ Find keys and get their respective data from SDL storage.
Only those entries that are matching prefix will be returned.
NOTE: In atomic action, if the prefix produces huge number of matches, that can have
a severe impact on system performance, due to DB is blocked for long time.
All the exceptions except SdlTypeError are derived from SdlException base class. Client
- can catch only that exception if separate handling for different shareddatalayer error
- situations is not needed. Exception SdlTypeError is derived from build-in TypeError and it
- indicates misuse of the SDL API.
+ can catch only that exception if separate handling for different SDL error situations is
+ not needed. Exception SdlTypeError is derived from build-in TypeError and it indicates
+ misuse of the SDL API.
Args:
ns (str): Namespace under which this operation is targeted.
Raises:
SdlTypeError: If function's argument is of an inappropriate type.
- NotConnected: If shareddatalayer is not connected to the backend data storage.
+ NotConnected: If SDL is not connected to the backend data storage.
RejectedByBackend: If backend data storage rejects the request.
BackendError: If the backend data storage fails to process the request.
"""
pass
-
@abstractmethod
def remove(self, ns: str, keys: Union[str, Set[str]]) -> None:
"""
- Remove data from shared data layer storage. Existing keys are removed.
+ Remove data from SDL storage. Existing keys are removed.
Removing is done atomically, i.e. either all succeeds, or all fails.
All the exceptions except SdlTypeError are derived from SdlException base class. Client
- can catch only that exception if separate handling for different shareddatalayer error
- situations is not needed. Exception SdlTypeError is derived from build-in TypeError and it
- indicates misuse of the SDL API.
+ can catch only that exception if separate handling for different SDL error situations is
+ not needed. Exception SdlTypeError is derived from build-in TypeError and it indicates
+ misuse of the SDL API.
Args:
ns (str): Namespace under which this operation is targeted.
Raises:
SdlTypeError: If function's argument is of an inappropriate type.
- NotConnected: If shareddatalayer is not connected to the backend data storage.
+ NotConnected: If SDL is not connected to the backend data storage.
RejectedByBackend: If backend data storage rejects the request.
BackendError: If the backend data storage fails to process the request.
"""
pass
-
@abstractmethod
def remove_if(self, ns: str, key: str, data: bytes) -> bool:
"""
- Conditionally remove data from shared data layer storage if the current data value matches
- the user's last known value.
+ Conditionally remove data from SDL storage if the current data value matches the user's
+ last known value.
All the exceptions except SdlTypeError are derived from SdlException base class. Client
- can catch only that exception if separate handling for different shareddatalayer error
- situations is not needed. Exception SdlTypeError is derived from build-in TypeError and it
- indicates misuse of the SDL API.
+ can catch only that exception if separate handling for different SDL error situations is
+ not needed. Exception SdlTypeError is derived from build-in TypeError and it indicates
+ misuse of the SDL API.
Args:
ns (str): Namespace under which this operation is targeted.
Raises:
SdlTypeError: If function's argument is of an inappropriate type.
- NotConnected: If shareddatalayer is not connected to the backend data storage.
+ NotConnected: If SDL is not connected to the backend data storage.
RejectedByBackend: If backend data storage rejects the request.
BackendError: If the backend data storage fails to process the request.
"""
pass
-
@abstractmethod
def remove_all(self, ns: str) -> None:
"""
No prior knowledge about the keys in the given namespace exists, thus operation is not
guaranteed to be atomic or isolated.
All the exceptions except SdlTypeError are derived from SdlException base class. Client
- can catch only that exception if separate handling for different shareddatalayer error
- situations is not needed. Exception SdlTypeError is derived from build-in TypeError and it
- indicates misuse of the SDL API.
+ can catch only that exception if separate handling for different SDL error situations is
+ not needed. Exception SdlTypeError is derived from build-in TypeError and it indicates
+ misuse of the SDL API.
Args:
ns (str): Namespace under which this operation is targeted.
Raises:
SdlTypeError: If function's argument is of an inappropriate type.
- NotConnected: If shareddatalayer is not connected to the backend data storage.
+ NotConnected: If SDL is not connected to the backend data storage.
RejectedByBackend: If backend data storage rejects the request.
BackendError: If the backend data storage fails to process the request.
"""
pass
-
@abstractmethod
def add_member(self, ns: str, group: str, members: Union[bytes, Set[bytes]]) -> None:
"""
- Add new members to a shared data layer group under the namespace.
+ Add new members to a SDL group under the namespace.
- Shared data layer groups are identified by their name, which is a key in storage. Shared
- data layer groups are unordered collections of members where each member is unique. If
- a member to be added is already a member of the group, its addition is silently ignored. If
- the group does not exist, it is created, and specified members are added to the group.
+ SDL groups are identified by their name, which is a key in storage. SDL groups are
+ unordered collections of members where each member is unique. If a member to be added is
+ already a member of the group, its addition is silently ignored. If the group does not
+ exist, it is created, and specified members are added to the group.
All the exceptions except SdlTypeError are derived from SdlException base class. Client
- can catch only that exception if separate handling for different shareddatalayer error
- situations is not needed. Exception SdlTypeError is derived from build-in TypeError and it
- indicates misuse of the SDL API.
+ can catch only that exception if separate handling for different SDL error situations is
+ not needed. Exception SdlTypeError is derived from build-in TypeError and it indicates
+ misuse of the SDL API.
Args:
ns (str): Namespace under which this operation is targeted.
Raises:
SdlTypeError: If function's argument is of an inappropriate type.
- NotConnected: If shareddatalayer is not connected to the backend data storage.
+ NotConnected: If SDL is not connected to the backend data storage.
RejectedByBackend: If backend data storage rejects the request.
BackendError: If the backend data storage fails to process the request.
"""
pass
-
@abstractmethod
def remove_member(self, ns: str, group: str, members: Union[bytes, Set[bytes]]) -> None:
"""
- Remove members from a shared data layer group.
+ Remove members from a SDL group.
- Shared data layer groups are unordered collections of members where each member is unique.
- If a member to be removed does not exist in the group, its removal is silently ignored. If
- a group does not exist, it is treated as an empty group and hence members removal is
- silently ignored.
+ SDL groups are unordered collections of members where each member is unique. If a member to
+ be removed does not exist in the group, its removal is silently ignored. If a group does
+ not exist, it is treated as an empty group and hence members removal is silently ignored.
All the exceptions except SdlTypeError are derived from SdlException base class. Client
- can catch only that exception if separate handling for different shareddatalayer error
- situations is not needed. Exception SdlTypeError is derived from build-in TypeError and it
- indicates misuse of the SDL API.
+ can catch only that exception if separate handling for different SDL error situations is
+ not needed. Exception SdlTypeError is derived from build-in TypeError and it indicates
+ misuse of the SDL API.
Args:
ns (str): Namespace under which this operation is targeted.
Raises:
SdlTypeError: If function's argument is of an inappropriate type.
- NotConnected: If shareddatalayer is not connected to the backend data storage.
+ NotConnected: If SDL is not connected to the backend data storage.
RejectedByBackend: If backend data storage rejects the request.
BackendError: If the backend data storage fails to process the request.
"""
pass
-
@abstractmethod
def remove_group(self, ns: str, group: str) -> None:
"""
- Remove a shared data layer group along with its members.
+ Remove a SDL group along with its members.
- Shared data layer groups are unordered collections of members where each member is unique.
- If a group to be removed does not exist, its removal is silently ignored.
+ SDL groups are unordered collections of members where each member is unique. If a group to
+ be removed does not exist, its removal is silently ignored.
All the exceptions except SdlTypeError are derived from SdlException base class. Client
- can catch only that exception if separate handling for different shareddatalayer error
- situations is not needed. Exception SdlTypeError is derived from build-in TypeError and it
- indicates misuse of the SDL API.
+ can catch only that exception if separate handling for different SDL error situations is
+ not needed. Exception SdlTypeError is derived from build-in TypeError and it indicates
+ misuse of the SDL API.
Args:
ns (str): Namespace under which this operation is targeted.
Raises:
SdlTypeError: If function's argument is of an inappropriate type.
- NotConnected: If shareddatalayer is not connected to the backend data storage.
+ NotConnected: If SDL is not connected to the backend data storage.
RejectedByBackend: If backend data storage rejects the request.
BackendError: If the backend data storage fails to process the request.
"""
pass
-
@abstractmethod
def get_members(self, ns: str, group: str) -> Set[bytes]:
"""
- Get all the members of a shared data layer group.
+ Get all the members of a SDL group.
- Shared data layer groups are unordered collections of members where each member is unique.
- If the group does not exist, empty set is returned.
+ SDL groups are unordered collections of members where each member is unique. If the group
+ does not exist, empty set is returned.
All the exceptions except SdlTypeError are derived from SdlException base class. Client
- can catch only that exception if separate handling for different shareddatalayer error
- situations is not needed. Exception SdlTypeError is derived from build-in TypeError and it
- indicates misuse of the SDL API.
+ can catch only that exception if separate handling for different SDL error situations is
+ not needed. Exception SdlTypeError is derived from build-in TypeError and it indicates
+ misuse of the SDL API.
Args:
ns (str): Namespace under which this operation is targeted.
Raises:
SdlTypeError: If function's argument is of an inappropriate type.
- NotConnected: If shareddatalayer is not connected to the backend data storage.
+ NotConnected: If SDL is not connected to the backend data storage.
RejectedByBackend: If backend data storage rejects the request.
BackendError: If the backend data storage fails to process the request.
"""
pass
-
@abstractmethod
def is_member(self, ns: str, group: str, member: bytes) -> bool:
"""
- Validate if a given member is in the shared data layer group.
+ Validate if a given member is in the SDL group.
- Shared data layer groups are unordered collections of members where each member is unique.
- If the group does not exist, false is returned.
+ SDL groups are unordered collections of members where each member is unique. If the group
+ does not exist, false is returned.
All the exceptions except SdlTypeError are derived from SdlException base class. Client
- can catch only that exception if separate handling for different shareddatalayer error
- situations is not needed. Exception SdlTypeError is derived from build-in TypeError and it
- indicates misuse of the SDL API.
+ can catch only that exception if separate handling for different SDL error situations is
+ not needed. Exception SdlTypeError is derived from build-in TypeError and it indicates
+ misuse of the SDL API.
Args:
ns (str): Namespace under which this operation is targeted.
Raises:
SdlTypeError: If function's argument is of an inappropriate type.
- NotConnected: If shareddatalayer is not connected to the backend data storage.
+ NotConnected: If SDL is not connected to the backend data storage.
RejectedByBackend: If backend data storage rejects the request.
BackendError: If the backend data storage fails to process the request.
"""
pass
-
@abstractmethod
def group_size(self, ns: str, group: str) -> int:
"""
Return the number of members in a group.
- Shared data layer groups are unordered collections of members where each member is unique.
- If the group does not exist, value 0 is returned.
+ SDL groups are unordered collections of members where each member is unique. If the group
+ does not exist, value 0 is returned.
All the exceptions except SdlTypeError are derived from SdlException base class. Client
- can catch only that exception if separate handling for different shareddatalayer error
- situations is not needed. Exception SdlTypeError is derived from build-in TypeError and it
- indicates misuse of the SDL API.
+ can catch only that exception if separate handling for different SDL error situations is
+ not needed. Exception SdlTypeError is derived from build-in TypeError and it indicates
+ misuse of the SDL API.
Args:
ns (str): Namespace under which this operation is targeted.
Raises:
SdlTypeError: If function's argument is of an inappropriate type.
- NotConnected: If shareddatalayer is not connected to the backend data storage.
+ NotConnected: If SDL is not connected to the backend data storage.
RejectedByBackend: If backend data storage rejects the request.
BackendError: If the backend data storage fails to process the request.
"""
pass
-
@abstractmethod
def get_lock_resource(self, ns: str, resource: str,
expiration: Union[int, float]) -> SyncLockAbc:
"""
- Return a lock resource for shared data layer.
+ Return a lock resource for SDL.
A lock resource instance is created per namespace and it is identified by its `name` within
a namespace. A `get_lock_resource` returns a lock resource instance, it does not acquire
a lock. Lock resource provides lock handling methods such as acquiring a lock, extend
expiration time and releasing a lock.
All the exceptions except SdlTypeError are derived from SdlException base class. Client
- can catch only that exception if separate handling for different shareddatalayer error
- situations is not needed. Exception SdlTypeError is derived from build-in TypeError and it
- indicates misuse of the SDL API.
+ can catch only that exception if separate handling for different SDL error situations is
+ not needed. Exception SdlTypeError is derived from build-in TypeError and it indicates
+ misuse of the SDL API.
Args:
ns (str): Namespace under which this operation is targeted.
- resource (str): Resource is used within namespace as a key for a lock entry in
- shareddatalayer.
+ resource (str): Resource is used within namespace as a key for a lock entry in SDL.
expiration (int, float): Expiration time of a lock
Returns:
Raises:
SdlTypeError: If function's argument is of an inappropriate type.
- NotConnected: If shareddatalayer is not connected to the backend data storage.
+ NotConnected: If SDL is not connected to the backend data storage.
RejectedByBackend: If backend data storage rejects the request.
BackendError: If the backend data storage fails to process the request.
"""
Code Review / ric-plt / sdlpy.git / blobdiff