diff --git a/doc/advanced_data_structures.rst b/doc/advanced_topics.rst similarity index 76% rename from doc/advanced_data_structures.rst rename to doc/advanced_topics.rst index 080834872..ce4a37dc6 100644 --- a/doc/advanced_data_structures.rst +++ b/doc/advanced_topics.rst @@ -1,11 +1,11 @@ -****************************** -Advanced Data Structure Topics -****************************** +*************** +Advanced Topics +*************** This page of documentation is reserved for advanced topics in SmartRedis data structures that may not be needed for all users. -.. _advanced_data_structures_dataset_aggregation: +.. _advanced_topics_dataset_aggregation: Dataset Aggregation =================== @@ -14,7 +14,7 @@ In addition to the ability to work with individual datasets, SmartRedis offers users the manage lists of datasets and work with them collectively. This is particularly useful for producer/consumer relationships. -The DataSet Aggregation API stores multiple ``DataSet`` objects +The DataSet Aggregation API manages references to multiple ``DataSet`` objects on one or more database nodes through an interface referred to as ``aggregation lists``. An ``aggregation list`` in SmartRedis stores references to @@ -24,10 +24,10 @@ subsequently, ``SmartRedis`` clients in the same application or a different application can retrieve some or all of the ``DataSet`` objects referenced in that ``aggregation list``. -Appending to a DataSet ----------------------- +Appending to a DataSet aggregation list +--------------------------------------- -For example, the C++ client function to append a ``DataSet`` to an +The C++ client function to append a reference to a ``DataSet`` to an aggregation list is shown below: .. code-block:: cpp @@ -36,19 +36,22 @@ aggregation list is shown below: void append_to_list(const std::string& list_name, const DataSet& dataset); -The above function will append the provided ``DataSet`` to the +NOTE: The ``DataSet`` must have already been added to the database via +the ``put_dataset()`` method in the SmartRedis ``Client``. + +The above function will append the a reference to the provided ``DataSet`` to the ``aggregation list``, which can be referenced in all user-facing functions by the provided list name. Note that a list can be appended by any client in the same or different application. Implicitly, all -DataSets, when appended, are added to the end of the list. If the list does not +``DataSets``, when appended, are added to the end of the list. If the list does not already exist, it is automatically created. -Retrieving DataSets from an aggregation list --------------------------------------------- +Retrieving the DataSets in an aggregation list +---------------------------------------------- -To retrieve ``aggregation list`` contents, -the SmartRedis ``Client`` method provides an API function that -will return an iterable container with all of the ``DataSet`` objects +To retrieve the ``DataSet`` referenced in an ``aggregation list``, +the SmartRedis ``Client`` provides an API function that +returns an iterable object containing all of ``DataSets`` appended to the ``aggregation list``. For example, the C++ client function to retrieve the entire ``aggregation list`` contents is shown below: @@ -67,6 +70,11 @@ list: const int start_index, const int end_index); +The start_index and end_index may be specified as negative numbers. +In this case, the offset is from the most recently appended DataSets. +For example, an offset of -1 is the last element in the list, and -3 is the +antepenultimate DataSet. + An application can determine how many DataSets are in an aggregation List via the following API: @@ -75,6 +83,7 @@ via the following API: # C++ aggregation list length query int get_list_length(const std::string& list_name); + Synchronization --------------- diff --git a/doc/data_structures.rst b/doc/data_structures.rst index 3de3253ba..2a1b86467 100644 --- a/doc/data_structures.rst +++ b/doc/data_structures.rst @@ -329,7 +329,7 @@ Aggregating SmartRedis also supports an advanced API for working with aggregate lists of DataSets; details may be found -:ref:`here <_advanced_data_structures_dataset_aggregation>`. +:ref:`here <_advanced_topics_dataset_aggregation>`. Model ===== diff --git a/doc/index.rst b/doc/index.rst index 6f4c85ce6..2a5f5ed90 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -9,11 +9,11 @@ overview data_structures - advanced_data_structures dataset_conversions installation testing runtime + advanced_topics .. toctree:: :maxdepth: 2