diff --git a/AUTHORS.md b/AUTHORS.md index 63d1877..5800355 100644 --- a/AUTHORS.md +++ b/AUTHORS.md @@ -1,10 +1,17 @@ PSync authors ============= -## Author(s): +## Main Project Author(s): + +The University of Memphis: * Ashlesh Gawande * Minsheng Zhang +* Lan Wang + +## Contributer(s): + +* Junxiao Shi ## Technical advisor(s): @@ -12,4 +19,4 @@ PSync authors ## Special thanks to: -* Davide Pesavento +* Davide Pesavento \ No newline at end of file diff --git a/docs/RELEASE-NOTES.rst b/docs/RELEASE-NOTES.rst new file mode 100644 index 0000000..43c2a86 --- /dev/null +++ b/docs/RELEASE-NOTES.rst @@ -0,0 +1,4 @@ +PSync Release Notes +=================== + +.. include:: release-notes-latest.rst \ No newline at end of file diff --git a/docs/_static/.gitignore b/docs/_static/.gitignore new file mode 100644 index 0000000..d6b7ef3 --- /dev/null +++ b/docs/_static/.gitignore @@ -0,0 +1,2 @@ +* +!.gitignore diff --git a/docs/conf.py b/docs/conf.py index f27bd34..425f489 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -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/" diff --git a/docs/doxygen.conf.in b/docs/doxygen.conf.in index bcde9c6..95b2bbe 100644 --- a/docs/doxygen.conf.in +++ b/docs/doxygen.conf.in @@ -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 diff --git a/docs/examples.rst b/docs/examples.rst new file mode 100644 index 0000000..9427dfa --- /dev/null +++ b/docs/examples.rst @@ -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 diff --git a/docs/index.rst b/docs/index.rst index d707098..226ca26 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -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 `_. 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 `_ 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 +`__. + +PSync Documentation +------------------- + +.. toctree:: + :hidden: + :maxdepth: 3 + + install + examples + RELEASE-NOTES + releases + +- :doc:`install` +- :doc:`examples` +- :doc:`RELEASE-NOTES` +- :doc:`releases` \ No newline at end of file diff --git a/docs/install.rst b/docs/install.rst new file mode 100644 index 0000000..64a96f6 --- /dev/null +++ b/docs/install.rst @@ -0,0 +1,21 @@ +PSync Installation Instructions +=============================== + +.. toctree:: +.. + +Prerequisites +------------- + +- `ndn-cxx `_ and its dependencies + +Build +----- + +Execute the following commands to build PSync: + +:: + + ./waf configure + ./waf + sudo ./waf install \ No newline at end of file diff --git a/docs/named_data_theme/layout.html b/docs/named_data_theme/layout.html index 3d9a27d..aa25686 100644 --- a/docs/named_data_theme/layout.html +++ b/docs/named_data_theme/layout.html @@ -40,9 +40,7 @@

{{ _('Developer documentation') }}

{%- endblock %} diff --git a/docs/release-notes-latest.rst b/docs/release-notes-latest.rst new file mode 120000 index 0000000..9f2f502 --- /dev/null +++ b/docs/release-notes-latest.rst @@ -0,0 +1 @@ +release-notes/release-notes-0.1.0.rst \ No newline at end of file diff --git a/docs/release-notes/release-notes-0.1.0.rst b/docs/release-notes/release-notes-0.1.0.rst new file mode 100644 index 0000000..528f04e --- /dev/null +++ b/docs/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 `_. 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 `_ 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. diff --git a/docs/releases.rst b/docs/releases.rst new file mode 100644 index 0000000..6d904e2 --- /dev/null +++ b/docs/releases.rst @@ -0,0 +1,8 @@ +PSync Versions +++++++++++++++ + +.. toctree:: + :hidden: + :maxdepth: 1 + + release-notes/release-notes-0.1.0 \ No newline at end of file