SunnyQjm/PSync
1
0 Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

docs: improve formatting and document structure

Browse Source 
Change-Id: I4b0b4cc3eae000aa1c988c5d308c3f78052ad96d
This commit is contained in:
Davide Pesavento committed 2023-01-05 04:07:05 -05:00
1 parent 59f6fabe50
commit 36651f17f3
9 files changed
+129 -141
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

.jenkins.d/00-deps.sh
+1 -1
View File
@@ -21,7 +21,7 @@ set -x
if [[ $ID == macos ]]; then
if [[ -n $GITHUB_ACTIONS ]]; then
export HOMEBREW_NO_INSTALL_UPGRADE=1
export HOMEBREW_NO_INSTALLED_DEPENDENTS_CHECK=1
fi
brew update
brew install --formula "${FORMULAE[@]}"
COPYING.md
+1 -2
View File
@@ -18,9 +18,8 @@ PSync relies on third-party software, licensed under the following licenses:
- The waf build system is licensed under the terms of the
[BSD license](https://github.com/named-data/PSync/blob/master/waf)
The LGPL and GPL licenses are provided below in this file. For more information
about these licenses, see https://www.gnu.org/licenses/
about these licenses, see <https://www.gnu.org/licenses/>
--------------------------------------------------------------------------------
README.md
+5 -6
View File
@@ -43,12 +43,11 @@ Please submit any bug reports or feature requests to the
## Contributing
We greatly appreciate contributions to the PSync code base, provided that they are
licensed under the LGPL 3.0+ or a compatible license (see below).
If you are new to the NDN software community, please read the
[Contributor's Guide](https://github.com/named-data/.github/blob/master/CONTRIBUTING.md)
to get started.
licensed under the GNU LGPL version 3 or a compatible license.
If you are new to the NDN software community, please read our [Contributor's Guide](
https://github.com/named-data/.github/blob/master/CONTRIBUTING.md) to get started.
## License
PSync is an open source project licensed under the LGPL version 3.
See [`COPYING.md`](COPYING.md) for more information.
PSync is free software distributed under the GNU Lesser General Public License version 3.
See [`COPYING.md`](COPYING.md) for details.
docs/conf.py
+1 -1
View File
@@ -10,7 +10,7 @@ import sys
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
project = 'PSync: Partial/Full Synchronization Protocol for NDN'
copyright = 'Copyright © 2018-2022 Named Data Networking Project.'
copyright = 'Copyright © 2018-2023 Named Data Networking Project.'
author = 'Named Data Networking Project'
# The short X.Y version.
docs/examples.rst
+83 -97
View File
@@ -1,155 +1,141 @@
Examples
========
By default, examples in ``examples/`` folder are not built. To enable them, use
``--with-examples`` configure option. For example:
The example programs in the ``examples/`` subdirectory are not built by default.
To enable them, use the ``--with-examples`` configure option:
.. code-block:: bash
./waf configure --with-examples
./waf
Example binary can be found under ``build/examples``:
Once built, the example binaries can be found under ``build/examples/``:
* Full sync: ``psync-full-sync``
* Partial sync: ``psync-producer`` and ``psync-consumer``
If the library is installed to the system using ``./waf install`` then the examples
are also installed and can be executed directly.
If the library is installed to the system using ``./waf install``, then the examples
will also be installed and can be executed directly.
Partial Sync Example
--------------------
Partial sync example of PSync has two parts: producer and consumer.
These can be run on a machine after starting NFD:
The partial sync example of PSync has two parts: producer and consumer.
These can be run on a machine after starting NFD.
Producer
^^^^^^^^
* Enable the logs for producer:
* Enable logging for the producer.
.. code-block:: bash
.. code-block:: bash
export NDN_LOG=examples.PartialSyncProducerApp=INFO
export NDN_LOG="examples.PartialSyncProducerApp=INFO"
* Start the producer that will listen on ``/sync`` and publish one update for each
of ``/a-0`` ... ``/a-9``.
* Start the producer that will listen on /sync and publish 1 update for /a-0 ... /a-9 each.
.. code-block:: bash
.. code-block:: bash
psync-producer /sync /a 10 1
psync-producer /sync /a 10 1
* Sample output::
* Sample output:
::
1546280442.096296 INFO: [examples.PartialSyncProducerApp] Publish: /a-1/1
1546280456.053138 INFO: [examples.PartialSyncProducerApp] Publish: /a-6/1
1546280458.210415 INFO: [examples.PartialSyncProducerApp] Publish: /a-8/1
1546280469.954134 INFO: [examples.PartialSyncProducerApp] Publish: /a-5/1
1546280472.487425 INFO: [examples.PartialSyncProducerApp] Publish: /a-2/1
1546280473.466515 INFO: [examples.PartialSyncProducerApp] Publish: /a-7/1
1546280481.882258 INFO: [examples.PartialSyncProducerApp] Publish: /a-0/1
1546280484.201229 INFO: [examples.PartialSyncProducerApp] Publish: /a-4/1
1546280489.348968 INFO: [examples.PartialSyncProducerApp] Publish: /a-9/1
1546280491.420391 INFO: [examples.PartialSyncProducerApp] Publish: /a-3/1
1546280442.096296 INFO: [examples.PartialSyncProducerApp] Publish: /a-1/1
1546280456.053138 INFO: [examples.PartialSyncProducerApp] Publish: /a-6/1
1546280458.210415 INFO: [examples.PartialSyncProducerApp] Publish: /a-8/1
1546280469.954134 INFO: [examples.PartialSyncProducerApp] Publish: /a-5/1
1546280472.487425 INFO: [examples.PartialSyncProducerApp] Publish: /a-2/1
1546280473.466515 INFO: [examples.PartialSyncProducerApp] Publish: /a-7/1
1546280481.882258 INFO: [examples.PartialSyncProducerApp] Publish: /a-0/1
1546280484.201229 INFO: [examples.PartialSyncProducerApp] Publish: /a-4/1
1546280489.348968 INFO: [examples.PartialSyncProducerApp] Publish: /a-9/1
1546280491.420391 INFO: [examples.PartialSyncProducerApp] Publish: /a-3/1
Consumer
^^^^^^^^
* In a new terminal, enable the logs for consumer:
* In a new terminal, enable logging for the consumer.
.. code-block:: bash
.. code-block:: bash
export NDN_LOG=examples.PartialSyncConsumerApp=INFO
export NDN_LOG="examples.PartialSyncConsumerApp=INFO"
* Run the consumer to subscribe to 5 random prefixes from the publisher on ``/sync``.
* Run the consumer to subscribe to 5 random prefixes from the publisher on /sync
.. code-block:: bash
psync-consumer /sync 5
.. code-block:: bash
psync-consumer /sync 5
* Sample output from the consumer shows that it received updates only
for the subscribed prefixes:
for the subscribed prefixes::
::
1546280436.502769 INFO: [examples.PartialSyncConsumerApp] Subscribing to: /a-7
1546280436.502888 INFO: [examples.PartialSyncConsumerApp] Subscribing to: /a-9
1546280436.502911 INFO: [examples.PartialSyncConsumerApp] Subscribing to: /a-8
1546280436.502934 INFO: [examples.PartialSyncConsumerApp] Subscribing to: /a-4
1546280436.502956 INFO: [examples.PartialSyncConsumerApp] Subscribing to: /a-5
1546280458.211188 INFO: [examples.PartialSyncConsumerApp] Update: /a-8/1
1546280469.954886 INFO: [examples.PartialSyncConsumerApp] Update: /a-5/1
1546280473.467116 INFO: [examples.PartialSyncConsumerApp] Update: /a-7/1
1546280484.256181 INFO: [examples.PartialSyncConsumerApp] Update: /a-4/1
1546280489.349793 INFO: [examples.PartialSyncConsumerApp] Update: /a-9/1
1546280436.502769 INFO: [examples.PartialSyncConsumerApp] Subscribing to: /a-7
1546280436.502888 INFO: [examples.PartialSyncConsumerApp] Subscribing to: /a-9
1546280436.502911 INFO: [examples.PartialSyncConsumerApp] Subscribing to: /a-8
1546280436.502934 INFO: [examples.PartialSyncConsumerApp] Subscribing to: /a-4
1546280436.502956 INFO: [examples.PartialSyncConsumerApp] Subscribing to: /a-5
1546280458.211188 INFO: [examples.PartialSyncConsumerApp] Update: /a-8/1
1546280469.954886 INFO: [examples.PartialSyncConsumerApp] Update: /a-5/1
1546280473.467116 INFO: [examples.PartialSyncConsumerApp] Update: /a-7/1
1546280484.256181 INFO: [examples.PartialSyncConsumerApp] Update: /a-4/1
1546280489.349793 INFO: [examples.PartialSyncConsumerApp] Update: /a-9/1
Full Sync Example
-----------------
To demonstrate full sync mode of PSync, ``psync-full-sync``
can be run on a machine after starting NFD:
To demonstrate the full sync mode of PSync, ``psync-full-sync`` can be run on a
machine after starting NFD.
* Enable logging for the full sync demo app.
* Enable the logs for full sync:
.. code-block:: bash
.. code-block:: bash
export NDN_LOG="examples.FullSyncApp=INFO"
export NDN_LOG=examples.FullSyncApp=INFO
* Run the full sync example with sync prefix ``/sync``, user prefix ``/a``,
and publish three updates for each user prefix: ``/a-0`` and ``/a-1``.
This will simulate node *a*.
.. code-block:: bash
* Run the full sync example with sync prefix /sync, user prefix /a,
and publish three updates for each user prefix: /a-0 and /a-1. This will simulate node a.
psync-full-sync /sync /a 2 3
.. code-block:: bash
* Repeat for another user prefix, to simulate node *b*.
psync-full-sync /sync /a 2 3
.. code-block:: bash
psync-full-sync /sync /b 2 3
* Repeat for another user prefix, to simulate node b:
We should see that node *a* and node *b* have received each other's updates.
.. code-block:: bash
* Sample output from node *a* shows that it received all updates from node *b*
successfully::
psync-full-sync /sync /b 2 3
1546282730.759387 INFO: [examples.FullSyncApp] Update /b-1/1
1546282741.143225 INFO: [examples.FullSyncApp] Publish: /a-1/1
1546282749.375854 INFO: [examples.FullSyncApp] Publish: /a-0/1
1546282750.263246 INFO: [examples.FullSyncApp] Update /b-0/1
1546282765.875118 INFO: [examples.FullSyncApp] Update /b-1/2
1546282783.777807 INFO: [examples.FullSyncApp] Publish: /a-0/2
1546282794.565507 INFO: [examples.FullSyncApp] Publish: /a-0/3
1546282794.896895 INFO: [examples.FullSyncApp] Publish: /a-1/2
1546282803.839416 INFO: [examples.FullSyncApp] Update /b-0/2
1546282804.785867 INFO: [examples.FullSyncApp] Update /b-1/3
1546282845.273772 INFO: [examples.FullSyncApp] Publish: /a-1/3
1546282855.102790 INFO: [examples.FullSyncApp] Update /b-0/3
We should see that node a and node b have received each other's updates.
* Sample output from node *b*::
* Sample output from node a shows that it received all updates
from node b successfully:
::
1546282730.759387 INFO: [examples.FullSyncApp] Update /b-1/1
1546282741.143225 INFO: [examples.FullSyncApp] Publish: /a-1/1
1546282749.375854 INFO: [examples.FullSyncApp] Publish: /a-0/1
1546282750.263246 INFO: [examples.FullSyncApp] Update /b-0/1
1546282765.875118 INFO: [examples.FullSyncApp] Update /b-1/2
1546282783.777807 INFO: [examples.FullSyncApp] Publish: /a-0/2
1546282794.565507 INFO: [examples.FullSyncApp] Publish: /a-0/3
1546282794.896895 INFO: [examples.FullSyncApp] Publish: /a-1/2
1546282803.839416 INFO: [examples.FullSyncApp] Update /b-0/2
1546282804.785867 INFO: [examples.FullSyncApp] Update /b-1/3
1546282845.273772 INFO: [examples.FullSyncApp] Publish: /a-1/3
1546282855.102790 INFO: [examples.FullSyncApp] Update /b-0/3
* Sample output from node b:
::
1546282730.758296 INFO: [examples.FullSyncApp] Publish: /b-1/1
1546282741.144027 INFO: [examples.FullSyncApp] Update /a-1/1
1546282749.376543 INFO: [examples.FullSyncApp] Update /a-0/1
1546282750.262244 INFO: [examples.FullSyncApp] Publish: /b-0/1
1546282765.296005 INFO: [examples.FullSyncApp] Publish: /b-1/2
1546282783.778769 INFO: [examples.FullSyncApp] Update /a-0/2
1546282794.566485 INFO: [examples.FullSyncApp] Update /a-0/3
1546282795.374339 INFO: [examples.FullSyncApp] Update /a-1/2
1546282803.838394 INFO: [examples.FullSyncApp] Publish: /b-0/2
1546282804.033214 INFO: [examples.FullSyncApp] Publish: /b-1/3
1546282845.274680 INFO: [examples.FullSyncApp] Update /a-1/3
1546282855.101780 INFO: [examples.FullSyncApp] Publish: /b-0/3
1546282730.758296 INFO: [examples.FullSyncApp] Publish: /b-1/1
1546282741.144027 INFO: [examples.FullSyncApp] Update /a-1/1
1546282749.376543 INFO: [examples.FullSyncApp] Update /a-0/1
1546282750.262244 INFO: [examples.FullSyncApp] Publish: /b-0/1
1546282765.296005 INFO: [examples.FullSyncApp] Publish: /b-1/2
1546282783.778769 INFO: [examples.FullSyncApp] Update /a-0/2
1546282794.566485 INFO: [examples.FullSyncApp] Update /a-0/3
1546282795.374339 INFO: [examples.FullSyncApp] Update /a-1/2
1546282803.838394 INFO: [examples.FullSyncApp] Publish: /b-0/2
1546282804.033214 INFO: [examples.FullSyncApp] Publish: /b-1/3
1546282845.274680 INFO: [examples.FullSyncApp] Update /a-1/3
1546282855.101780 INFO: [examples.FullSyncApp] Publish: /b-0/3
docs/index.rst
+21 -21
View File
@@ -1,5 +1,14 @@
PSync - Partial/Full Sync Library based on BF and IBF
=====================================================
PSync: Partial/Full Sync Library based on BF and IBF
====================================================
.. toctree::
:hidden:
:maxdepth: 2
install
examples
release-notes
releases
PSync is a C++ library for name synchronization that implements the `PSync protocol
<https://named-data.net/wp-content/uploads/2017/05/scalable_name-based_data_synchronization.pdf>`__.
@@ -11,31 +20,22 @@ list of the consumer.
PSync uses the `ndn-cxx <https://github.com/named-data/ndn-cxx>`__ library.
Documentation
-------------
- :doc:`install`
- :doc:`examples`
- :doc:`release-notes`
- :doc:`releases`
Contributing
------------
We greatly appreciate contributions to the PSync code base, provided that they are
licensed under the LGPL 3.0+ or a compatible license (see `COPYING.md
licensed under the GNU LGPL version 3 or a compatible license (see `COPYING.md
<https://github.com/named-data/PSync/blob/master/COPYING.md>`__ for more information).
If you are new to the NDN software community, please read the `Contributor's Guide
If you are new to the NDN software community, please read our `Contributor's Guide
<https://github.com/named-data/.github/blob/master/CONTRIBUTING.md>`__ to get started.
Please submit any bug reports or feature requests to the `PSync issue tracker
<https://redmine.named-data.net/projects/psync/issues>`__.
PSync Documentation
-------------------
.. toctree::
:hidden:
:maxdepth: 2
install
examples
release-notes
releases
- :doc:`install`
- :doc:`examples`
- :doc:`release-notes`
- :doc:`releases`
docs/release-notes/release-notes-0.1.0.rst
+4 -4
View File
@@ -4,12 +4,12 @@ PSync version 0.1.0
*Release date: January 25, 2019*
Version 0.1.0 is the initial release of PSync. The PSync library implements the `PSync protocol
<https://named-data.net/wp-content/uploads/2017/05/scalable_name-based_data_synchronization.pdf>`_.
<https://named-data.net/wp-content/uploads/2017/05/scalable_name-based_data_synchronization.pdf>`__.
It uses Invertible Bloom Lookup Table (IBLT), also known as Invertible Bloom Filter (IBF), to represent
the state of a producer in partial sync mode and the state of a node in full sync mode. An IBF is a
compact data structure where difference of two IBFs can be computed efficiently.
In partial sync, PSync uses a Bloom Filter to represent the subscription of list of the consumer.
PSync uses the `ndn-cxx <https://github.com/named-data/ndn-cxx>`_ library as NDN development
PSync uses the `ndn-cxx <https://github.com/named-data/ndn-cxx>`__ library as NDN development
library.
PSync is an open source project licensed under LGPL 3.0. We highly welcome all contributions to the PSync code base, provided that they can be licensed under LGPL 3.0+ or other compatible license.
@@ -30,6 +30,6 @@ PSync supports the following features:
- **Miscellaneous**
+ Uses ndn-cxx **SegmentFetcher** to segment hello and sync data.
+ Uses ndn-cxx ``SegmentFetcher`` to segment hello and sync data.
+ Provide a SegmentPublisher that can be used by other NDN applications.
+ Examples are provided in `examples` folder to show how to use the library.
+ Examples are provided in ``examples`` folder to show how to use the library.
docs/release-notes/release-notes-0.2.0.rst
+4 -4
View File
@@ -6,12 +6,12 @@ PSync version 0.2.0
New features
^^^^^^^^^^^^
- **breaking change** Compress Sync Data in Full Sync by default (:issue:`5061`, :issue:`4917`)
- *(breaking change)* Compress Sync Data in Full Sync by default (:issue:`5061`, :issue:`4917`)
- Support various compression schemes for compressing IBF and Sync Data (:issue:`5061`)
Changes
^^^^^^^
Improvements and bug fixes
^^^^^^^^^^^^^^^^^^^^^^^^^^
- Use constant interest timeout for (discovery) sync Interest in Segment Fetcher (:issue:`4945`)
- Use constant interest timeout for (discovery) Sync Interest in ``SegmentFetcher`` (:issue:`4945`)
- Make default jitter shorter, react to NACK after jitter
- Use ``boost::bimap`` instead of two ``std::map`` variables to store hash to prefix matching
docs/release-notes/release-notes-0.3.0.rst
+9 -5
View File
@@ -8,18 +8,22 @@ Meanwhile, it is *recommended* to use GCC >= 7.4.0 and Boost >= 1.65.1.
This effectively drops official support for Ubuntu 16.04 when using distribution-provided Boost
packages -- PSync may still work on this platform, but we provide no official support for it.
We have taken some steps to be endian safe but PSync is not completely endian safe yet (:issue:`4818`)
New features
^^^^^^^^^^^^
- **breaking** Consumer: change hello data callback to include sequence number (:issue:`5122`)
- *(breaking change)* Consumer: change hello data callback to include sequence number (:issue:`5122`)
Improvements and bug fixes
^^^^^^^^^^^^^^^^^^^^^^^^^^
- **breaking** IBLT: make encoding endian safe (:issue:`5076`)
- *(breaking change)* IBLT: make encoding endian safe (:issue:`5076`)
- Reset cached wire encoding after adding names (:issue:`5083`)
- Consumer reacts faster on sync Interest timeout (:issue:`5124`)
- Consumer reacts faster on Sync Interest timeout (:issue:`5124`)
- Move private classes and functions to ``psync::detail`` namespace
- Improved unit tests
Known issues
^^^^^^^^^^^^
- We have taken some steps to be endian safe but PSync is not completely endian safe yet
(:issue:`4818`)