docs: prepare version 0.1.0 release notes
Change-Id: I588e97d4dec76cd6f4ffbda487de5b7cbe412219
This commit is contained in:
Ashlesh Gawande committed
1 parent
e5fdcc3744
commit
465d149ae0
12 files changed
+285
-14
No files matched your search
+9
-2
@@ -1,10 +1,17 @@
|
||||
PSync authors
|
||||
=============
|
||||
|
||||
## Author(s):
|
||||
## Main Project Author(s):
|
||||
|
||||
The University of Memphis:
|
||||
|
||||
* Ashlesh Gawande <https://www.linkedin.com/in/agawande>
|
||||
* Minsheng Zhang <https://www.linkedin.com/in/minsheng-zhang-032023a1>
|
||||
* Lan Wang <http://www.cs.memphis.edu/~lanwang/>
|
||||
|
||||
## Contributer(s):
|
||||
|
||||
* Junxiao Shi <https://www.linkedin.com/in/shijunxiao>
|
||||
|
||||
## Technical advisor(s):
|
||||
|
||||
@@ -12,4 +19,4 @@ PSync authors
|
||||
|
||||
## Special thanks to:
|
||||
|
||||
* Davide Pesavento <https://www.linkedin.com/in/davidepesavento>
|
||||
* Davide Pesavento <https://www.linkedin.com/in/davidepesavento>
|
||||
@@ -0,0 +1,4 @@
|
||||
PSync Release Notes
|
||||
===================
|
||||
|
||||
.. include:: release-notes-latest.rst
|
||||
@@ -0,0 +1,2 @@
|
||||
*
|
||||
!.gitignore
|
||||
+5
-5
@@ -20,7 +20,7 @@ import datetime
|
||||
# If extensions (or modules to document with autodoc) are in another directory,
|
||||
# add these directories to sys.path here. If the directory is relative to the
|
||||
# documentation root, use os.path.abspath to make it absolute, like shown here.
|
||||
#sys.path.insert(0, os.path.abspath('.'))
|
||||
sys.path.insert(0, os.path.abspath('.'))
|
||||
|
||||
# -- General configuration ------------------------------------------------
|
||||
|
||||
@@ -64,8 +64,8 @@ source_suffix = '.rst'
|
||||
master_doc = 'index'
|
||||
|
||||
# General information about the project.
|
||||
project = u'PSync: A Synchronization Protocol in NDN'
|
||||
copyright = u'{}, Named Data Networking Project'.format(datetime.date.today().year)
|
||||
project = u'PSync: A Synchronization Protocol for NDN'
|
||||
copyright = u'2018-{}, Named Data Networking Project'.format(datetime.date.today().year)
|
||||
|
||||
# The language for content autogenerated by Sphinx. Refer to documentation
|
||||
# for a list of supported languages.
|
||||
@@ -140,7 +140,7 @@ html_theme_path = ['./']
|
||||
# Add any paths that contain custom static files (such as style sheets) here,
|
||||
# relative to this directory. They are copied after the builtin static files,
|
||||
# so a file named "default.css" will overwrite the builtin "default.css".
|
||||
# html_static_path = ['_static']
|
||||
html_static_path = ['_static']
|
||||
|
||||
# Add any extra paths that contain custom files (such as robots.txt or
|
||||
# .htaccess) here, relative to this directory. These files are copied
|
||||
@@ -256,4 +256,4 @@ if os.getenv('GOOGLE_ANALYTICS', None):
|
||||
googleanalytics_id = os.environ['GOOGLE_ANALYTICS']
|
||||
googleanalytics_enabled = True
|
||||
|
||||
exclude_patterns = ['RELEASE_NOTES.rst']
|
||||
redmine_project_url = "https://redmine.named-data.net/"
|
||||
@@ -140,7 +140,7 @@ INLINE_INHERITED_MEMB = YES
|
||||
# shortest path that makes the file name unique will be used
|
||||
# The default value is: YES.
|
||||
|
||||
FULL_PATH_NAMES = NO
|
||||
FULL_PATH_NAMES = YES
|
||||
|
||||
# The STRIP_FROM_PATH tag can be used to strip a user-defined part of the path.
|
||||
# Stripping is only done if one of the specified strings matches the left-hand
|
||||
@@ -152,7 +152,7 @@ FULL_PATH_NAMES = NO
|
||||
# will be relative from the directory where doxygen is started.
|
||||
# This tag requires that the tag FULL_PATH_NAMES is set to YES.
|
||||
|
||||
STRIP_FROM_PATH =
|
||||
STRIP_FROM_PATH = ..
|
||||
|
||||
# The STRIP_FROM_INC_PATH tag can be used to strip a user-defined part of the
|
||||
# path mentioned in the documentation of a class, which tells the reader which
|
||||
@@ -451,7 +451,7 @@ EXTRACT_STATIC = YES
|
||||
# for Java sources.
|
||||
# The default value is: YES.
|
||||
|
||||
EXTRACT_LOCAL_CLASSES = YES
|
||||
EXTRACT_LOCAL_CLASSES = NO
|
||||
|
||||
# This flag is only useful for Objective-C code. If set to YES, local methods,
|
||||
# which are defined in the implementation section but not in the interface are
|
||||
@@ -867,7 +867,7 @@ EXAMPLE_PATTERNS =
|
||||
# irrespective of the value of the RECURSIVE tag.
|
||||
# The default value is: NO.
|
||||
|
||||
EXAMPLE_RECURSIVE = NO
|
||||
EXAMPLE_RECURSIVE = YES
|
||||
|
||||
# The IMAGE_PATH tag can be used to specify one or more files or directories
|
||||
# that contain images that are to be included in the documentation (see the
|
||||
@@ -2051,7 +2051,11 @@ INCLUDE_FILE_PATTERNS =
|
||||
|
||||
PREDEFINED = DOXYGEN \
|
||||
PSYNC_PUBLIC_WITH_TESTS_ELSE_PRIVATE=private \
|
||||
NDN_CXX_DECLARE_WIRE_ENCODE_INSTANTIATIONS(x)=
|
||||
NDN_CXX_DECLARE_WIRE_ENCODE_INSTANTIATIONS(x)= \
|
||||
NDN_LOG_INIT(x)= \
|
||||
PUBLIC_WITH_TESTS_ELSE_PROTECTED=protected \
|
||||
PUBLIC_WITH_TESTS_ELSE_PRIVATE=private \
|
||||
PROTECTED_WITH_TESTS_ELSE_PRIVATE=private
|
||||
|
||||
# If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then this
|
||||
# tag can be used to specify a list of macro names that should be expanded. The
|
||||
|
||||
@@ -0,0 +1,158 @@
|
||||
PSync examples
|
||||
==============
|
||||
|
||||
By default, examples in ``examples/`` folder are not built. To enable them, use
|
||||
``--with-examples`` configure option. For example:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
./waf configure --with-examples
|
||||
./waf
|
||||
|
||||
|
||||
Example binary 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.
|
||||
|
||||
Partial Sync Example
|
||||
--------------------
|
||||
|
||||
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:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
export NDN_LOG=examples.PartialSyncProducerApp=INFO
|
||||
|
||||
|
||||
* Start the producer that will listen on /sync and publish 1 update for /a-0 ... /a-9 each.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
psync-producer /sync /a 10 1
|
||||
|
||||
|
||||
* Sample output:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
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:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
export NDN_LOG=examples.PartialSyncConsumerApp=INFO
|
||||
|
||||
|
||||
* Run the consumer to subscribe to 5 random prefixes from the publisher on /sync
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
psync-consumer /sync 5
|
||||
|
||||
|
||||
* Sample output from the consumer shows that it received updates only
|
||||
for the subscribed prefixes:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
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:
|
||||
|
||||
|
||||
* Enable the logs for full sync:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
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
|
||||
|
||||
psync-full-sync /sync /a 2 3
|
||||
|
||||
|
||||
* Repeat for another user prefix, to simulate node b:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
psync-full-sync /sync /b 2 3
|
||||
|
||||
We should see that node a and node b have received each other's updates.
|
||||
|
||||
|
||||
* Sample output from node a shows that it received all updates
|
||||
from node b successfully:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
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:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
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
|
||||
@@ -1,2 +1,36 @@
|
||||
PSYNC - Partial/Full Sync Library based on BF and IBF
|
||||
=====================================================
|
||||
|
||||
PSync is an ndn-cxx based C++ library for name synchronization that uses
|
||||
|
||||
PSync library implements the `PSync protocol <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 `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 (see ``COPYING.md`` for more
|
||||
detail). We highly welcome all contributions to the PSync code base, provided that
|
||||
they can be licensed under LGPL 3.0+ or other compatible license.
|
||||
|
||||
Please submit any bugs or issues to the `PSync issue tracker
|
||||
<https://redmine.named-data.net/projects/PSync/issues>`__.
|
||||
|
||||
PSync Documentation
|
||||
-------------------
|
||||
|
||||
.. toctree::
|
||||
:hidden:
|
||||
:maxdepth: 3
|
||||
|
||||
install
|
||||
examples
|
||||
RELEASE-NOTES
|
||||
releases
|
||||
|
||||
- :doc:`install`
|
||||
- :doc:`examples`
|
||||
- :doc:`RELEASE-NOTES`
|
||||
- :doc:`releases`
|
||||
@@ -0,0 +1,21 @@
|
||||
PSync Installation Instructions
|
||||
===============================
|
||||
|
||||
.. toctree::
|
||||
..
|
||||
|
||||
Prerequisites
|
||||
-------------
|
||||
|
||||
- `ndn-cxx <https://named-data.net/doc/ndn-cxx>`_ and its dependencies
|
||||
|
||||
Build
|
||||
-----
|
||||
|
||||
Execute the following commands to build PSync:
|
||||
|
||||
::
|
||||
|
||||
./waf configure
|
||||
./waf
|
||||
sudo ./waf install
|
||||
@@ -40,9 +40,7 @@
|
||||
|
||||
<h3>{{ _('Developer documentation') }}</h3>
|
||||
<ul>
|
||||
<li class="toctree-l1"><a class="reference external" href="https://redmine.named-data.net/projects/psync/wiki">PSync Wiki</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="doxygen/annotated.html">API documentation (doxygen)</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="code-style.html">ndn-cxx Code Style and Coding Guidelines</a></li>
|
||||
</ul>
|
||||
{%- endblock %}
|
||||
|
||||
|
||||
Symlink
+1
@@ -0,0 +1 @@
|
||||
release-notes/release-notes-0.1.0.rst
|
||||
@@ -0,0 +1,34 @@
|
||||
PSync version 0.1.0
|
||||
-------------------
|
||||
|
||||
Release date: January 25, 2019
|
||||
|
||||
Version 0.1.0 is the initial release of PSyncPSync library implements the `PSync protocol <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 `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.
|
||||
|
||||
PSync supports the following features:
|
||||
|
||||
- **Partial Synchronization**
|
||||
|
||||
+ Allows consumers to subscribe to a subset of a producer's offered prefixes.
|
||||
+ Consumer can sync with any replicated producer in the same sync group.
|
||||
+ A PartialProducer class to publish prefixes and updates.
|
||||
+ A Consumer class to subscribe to the producer (hello) and listen for updates (sync).
|
||||
|
||||
- **Full Synchronization**
|
||||
|
||||
+ Similar to ChronoSync, allows full synchronization of names amongst all the nodes in the sync group.
|
||||
+ FullProducer class can be used start syncing with a sync group.
|
||||
|
||||
- **Miscellaneous**
|
||||
|
||||
+ 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.
|
||||
@@ -0,0 +1,8 @@
|
||||
PSync Versions
|
||||
++++++++++++++
|
||||
|
||||
.. toctree::
|
||||
:hidden:
|
||||
:maxdepth: 1
|
||||
|
||||
release-notes/release-notes-0.1.0
|
||||
Reference in new issue
Block a user