include/sdl/doxygen.hpp

   1 /*
   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 /*
  18  * This source code is part of the near-RT RIC (RAN Intelligent Controller)
  19  * platform project (RICP).
  20 */
  21
  22 /**
  23  * @mainpage
  24  *
  25  * @section introduction_sec Introduction
  26  *
  27  * Shared Data Layer provides a lightweight, high-speed interface for accessing shared
  28  * data storage. The purpose is to enable utilizing clients to become stateless,
  29  * conforming with, e.g., the requirements of the fifth generation mobile networks.
  30  *
  31  * @section concepts_sec Concepts
  32  *
  33  * @subsection namespace_sec Namespace
  34  *
  35  * A shared data layer connection is instantiated to a namespace and data is always
  36  * read and modified within the namespace. Namespace provides data isolation across
  37  * clients.
  38  *
  39  * Namespace management is planned to be moved under a managing entity, a shared data
  40  * layer manager of sort, which handles the namespaces within a cluster, enforcing
  41  * some control over how the namespaces are created, utilized and load balanced as well
  42  * as dynamically scaling the underlying data storage resources. For now, however,
  43  * namespace naming needs to be manually coordinated between clients.
  44  *
  45  * @subsection data_sec Keys and data
  46  *
  47  * Clients save key-data pairs. Data is passed as byte vectors, any structure that
  48  * this data may have (e.g. a serialized JSON) is meaningful only to the client itself.
  49  * Clients are responsible for managing the keys within a namespace.
  50  *
  51  * @section compiling_clients_sec Compiling clients using shareddatalayer APIs
  52  *
  53  * The necessary compilation flags and libraries needed for compiling using shareddatalayer
  54  * APIs can be acquired with the <code>pkg-config</code> tool:
  55  *
  56  * \code
  57  * pkg-config --cflags libsdl
  58  * pkg-config --libs libsdl
  59  * \endcode
  60  *
  61  * @section usage_sec Usage
  62  *
  63  * @subsection async_api_sec Asynchronous API
  64  *
  65  * shareddatalayer::AsyncStorage API is used to access SDL data asynchronously.
  66  *
  67  * Instance is created with shareddatalayer::AsyncStorage::create() function.
  68  *
  69  * Functions shareddatalayer::AsyncStorage::fd() and shareddatalayer::AsyncStorage::handleEvents()
  70  * are used to integrate SDL to client's event loop.
  71  *
  72  * Optionally client may verify/wait that SDL (the database service in practice) is ready
  73  * with shareddatalayer::AsyncStorage::waitReadyAsync() function.
  74  *
  75  * @subsection sync_api_sec Synchronous API
  76  *
  77  * shareddatalayer::SyncStorage API is used to access SDL data synchronously.
  78  *
  79  * Functionally it is similar to AsyncStorage, with an exception that functions are blocking while
  80  * waiting response(s) from database.
  81  *
  82  */