examples: add library usage examples
refs: #4793
Change-Id: I660ed74bca55debd885b4cdefb230225ccdfe4ca
diff --git a/examples/README.md b/examples/README.md
new file mode 100644
index 0000000..bdce503
--- /dev/null
+++ b/examples/README.md
@@ -0,0 +1,141 @@
+PSync examples
+==============
+
+By default, examples in `examples/` folder are not built. To enable them, use
+`--with-examples` configure option. For example:
+
+ ./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:
+
+```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.
+
+```bash
+psync-producer /sync /a 10 1
+```
+
+- 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
+```
+
+### Consumer
+
+- In a new terminal, enable the logs for consumer:
+
+```bash
+export NDN_LOG=examples.PartialSyncConsumerApp=INFO
+```
+
+- Run the consumer to subscribe to 5 random prefixes from the publisher on /sync
+
+```bash
+psync-consumer /sync 5
+```
+
+- Sample output from the consumer shows that it received updates only
+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
+```
+
+## 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:
+
+```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.
+
+```bash
+psync-full-sync /sync /a 2 3
+```
+
+- Repeat for another user prefix, to simulate node b:
+
+```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:
+
+```
+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
+```
\ No newline at end of file
diff --git a/examples/consumer.cpp b/examples/consumer.cpp
new file mode 100644
index 0000000..8a83574
--- /dev/null
+++ b/examples/consumer.cpp
@@ -0,0 +1,115 @@
+/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */
+/*
+ * Copyright (c) 2014-2019, The University of Memphis
+ *
+ * This file is part of PSync.
+ * See AUTHORS.md for complete list of PSync authors and contributors.
+ *
+ * PSync is free software: you can redistribute it and/or modify it under the terms
+ * of the GNU General Public License as published by the Free Software Foundation,
+ * either version 3 of the License, or (at your option) any later version.
+ *
+ * PSync is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
+ * without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
+ * PURPOSE. See the GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License along with
+ * PSync, e.g., in COPYING.md file. If not, see <http://www.gnu.org/licenses/>.
+ **/
+
+#include <PSync/consumer.hpp>
+
+#include <ndn-cxx/name.hpp>
+#include <ndn-cxx/util/logger.hpp>
+#include <ndn-cxx/util/random.hpp>
+
+#include <iostream>
+
+NDN_LOG_INIT(examples.PartialSyncConsumerApp);
+
+class PSyncConsumer
+{
+public:
+ /**
+ * @brief Initialize consumer and start hello process
+ *
+ * 0.001 is the false positive probability of the bloom filter
+ *
+ * @param syncPrefix should be the same as producer
+ * @param nSub number of subscriptions is used for the bloom filter (subscription list) size
+ */
+ PSyncConsumer(const ndn::Name& syncPrefix, int nSub)
+ : m_nSub(nSub)
+ , m_consumer(syncPrefix, m_face,
+ std::bind(&PSyncConsumer::afterReceiveHelloData, this, _1),
+ std::bind(&PSyncConsumer::processSyncUpdate, this, _1),
+ m_nSub, 0.001)
+ , m_rng(ndn::random::getRandomNumberEngine())
+ {
+ // This starts the consumer side by sending a hello interest to the producer
+ // When the producer responds with hello data, afterReceiveHelloData is called
+ m_consumer.sendHelloInterest();
+ }
+
+ void
+ run()
+ {
+ m_face.processEvents();
+ }
+
+private:
+ void
+ afterReceiveHelloData(const std::vector<ndn::Name>& availSubs)
+ {
+ // Randomly subscribe to m_nSub prefixes
+ std::vector<ndn::Name> sensors = availSubs;
+
+ std::shuffle(sensors.begin(), sensors.end(), m_rng);
+
+ for (int i = 0; i < m_nSub; i++) {
+ NDN_LOG_INFO("Subscribing to: " << sensors[i]);
+ m_consumer.addSubscription(sensors[i]);
+ }
+
+ // After setting the subscription list, send the sync interest
+ // The sync interest contains the subscription list
+ // When new data is received for any subscribed prefix, processSyncUpdate is called
+ m_consumer.sendSyncInterest();
+ }
+
+ void
+ processSyncUpdate(const std::vector<psync::MissingDataInfo>& updates)
+ {
+ for (const auto& update : updates) {
+ for (uint64_t i = update.lowSeq; i <= update.highSeq; i++) {
+ // Data can now be fetched using the prefix and sequence
+ NDN_LOG_INFO("Update: " << update.prefix << "/" << i);
+ }
+ }
+ }
+
+private:
+ ndn::Face m_face;
+ int m_nSub;
+
+ psync::Consumer m_consumer;
+ ndn::random::RandomNumberEngine& m_rng;
+};
+
+int
+main(int argc, char* argv[])
+{
+ if (argc != 3) {
+ std::cout << "usage: " << argv[0] << " "
+ << "<sync-prefix> <number-of-subscriptions>" << std::endl;
+ return 1;
+ }
+
+ try {
+ PSyncConsumer consumer(argv[1], std::stoi(argv[2]));
+ consumer.run();
+ }
+ catch (const std::exception& e) {
+ NDN_LOG_ERROR(e.what());
+ }
+}
diff --git a/examples/full-sync.cpp b/examples/full-sync.cpp
new file mode 100644
index 0000000..56adaf0
--- /dev/null
+++ b/examples/full-sync.cpp
@@ -0,0 +1,128 @@
+/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */
+/*
+ * Copyright (c) 2014-2019, The University of Memphis
+ *
+ * This file is part of PSync.
+ * See AUTHORS.md for complete list of PSync authors and contributors.
+ *
+ * PSync is free software: you can redistribute it and/or modify it under the terms
+ * of the GNU General Public License as published by the Free Software Foundation,
+ * either version 3 of the License, or (at your option) any later version.
+ *
+ * PSync is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
+ * without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
+ * PURPOSE. See the GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License along with
+ * PSync, e.g., in COPYING.md file. If not, see <http://www.gnu.org/licenses/>.
+ **/
+
+#include <PSync/full-producer.hpp>
+
+#include <ndn-cxx/util/logger.hpp>
+#include <ndn-cxx/util/random.hpp>
+
+#include <iostream>
+
+NDN_LOG_INIT(examples.FullSyncApp);
+
+using namespace ndn::time_literals;
+
+class Producer
+{
+public:
+ /**
+ * @brief Initialize producer and schedule updates
+ *
+ * Set IBF size as 80 expecting 80 updates to IBF in a sync cycle
+ * Set syncInterestLifetime and syncReplyFreshness to 1.6 seconds
+ * userPrefix is the default user prefix, no updates are published on it in this example
+ */
+ Producer(const ndn::Name& syncPrefix, const std::string& userPrefix,
+ int numDataStreams, int maxNumPublish)
+ : m_scheduler(m_face.getIoService())
+ , m_fullProducer(80, m_face, syncPrefix, userPrefix,
+ std::bind(&Producer::processSyncUpdate, this, _1),
+ 1600_ms, 1600_ms)
+ , m_numDataStreams(numDataStreams)
+ , m_maxNumPublish(maxNumPublish)
+ , m_rng(ndn::random::getRandomNumberEngine())
+ , m_rangeUniformRandom(0, 60000)
+ {
+ // Add user prefixes and schedule updates for them in specified interval
+ for (int i = 0; i < m_numDataStreams; i++) {
+ ndn::Name prefix(userPrefix + "-" + ndn::to_string(i));
+
+ m_fullProducer.addUserNode(prefix);
+
+ m_scheduler.scheduleEvent(ndn::time::milliseconds(m_rangeUniformRandom(m_rng)),
+ [this, prefix] {
+ doUpdate(prefix);
+ });
+ }
+ }
+
+ void
+ run()
+ {
+ m_face.processEvents();
+ }
+
+private:
+ void
+ doUpdate(const ndn::Name& prefix)
+ {
+ m_fullProducer.publishName(prefix);
+
+ uint64_t seqNo = m_fullProducer.getSeqNo(prefix).value();
+ NDN_LOG_INFO("Publish: " << prefix << "/" << seqNo);
+
+ if (seqNo < m_maxNumPublish) {
+ m_scheduler.scheduleEvent(ndn::time::milliseconds(m_rangeUniformRandom(m_rng)),
+ [this, prefix] {
+ doUpdate(prefix);
+ });
+ }
+ }
+
+ void
+ processSyncUpdate(const std::vector<psync::MissingDataInfo>& updates)
+ {
+ for (const auto& update : updates) {
+ for (uint64_t i = update.lowSeq; i <= update.highSeq; i++) {
+ NDN_LOG_INFO("Update " << update.prefix << "/" << i);
+ }
+ }
+ }
+
+private:
+ ndn::Face m_face;
+ ndn::util::Scheduler m_scheduler;
+
+ psync::FullProducer m_fullProducer;
+
+ int m_numDataStreams;
+ uint64_t m_maxNumPublish;
+
+ ndn::random::RandomNumberEngine& m_rng;
+ std::uniform_int_distribution<> m_rangeUniformRandom;
+};
+
+int
+main(int argc, char* argv[])
+{
+ if (argc != 5) {
+ std::cout << "usage: " << argv[0] << " <syncPrefix> <user-prefix> "
+ << "<number-of-user-prefixes> <max-number-of-updates-per-user-prefix>"
+ << std::endl;
+ return 1;
+ }
+
+ try {
+ Producer producer(argv[1], argv[2], std::stoi(argv[3]), std::stoi(argv[4]));
+ producer.run();
+ }
+ catch (const std::exception& e) {
+ NDN_LOG_ERROR(e.what());
+ }
+}
diff --git a/examples/producer.cpp b/examples/producer.cpp
new file mode 100644
index 0000000..a56ec57
--- /dev/null
+++ b/examples/producer.cpp
@@ -0,0 +1,117 @@
+/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */
+/*
+ * Copyright (c) 2014-2019, The University of Memphis
+ *
+ * This file is part of PSync.
+ * See AUTHORS.md for complete list of PSync authors and contributors.
+ *
+ * PSync is free software: you can redistribute it and/or modify it under the terms
+ * of the GNU General Public License as published by the Free Software Foundation,
+ * either version 3 of the License, or (at your option) any later version.
+ *
+ * PSync is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
+ * without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
+ * PURPOSE. See the GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License along with
+ * PSync, e.g., in COPYING.md file. If not, see <http://www.gnu.org/licenses/>.
+ **/
+
+#include <PSync/partial-producer.hpp>
+
+#include <ndn-cxx/util/logger.hpp>
+#include <ndn-cxx/util/random.hpp>
+
+#include <iostream>
+
+NDN_LOG_INIT(examples.PartialSyncProducerApp);
+
+class PSyncPartialProducer
+{
+public:
+ /**
+ * @brief Initialize producer and schedule updates
+ *
+ * IBF size is set to 40 in m_producer as the expected number of update to IBF in a sync cycle
+ */
+ PSyncPartialProducer(const ndn::Name& syncPrefix, const std::string& userPrefix,
+ int nDataStreams, int maxNumPublish)
+ : m_scheduler(m_face.getIoService())
+ , m_producer(40, m_face, syncPrefix, userPrefix + "-0")
+ , m_nDataStreams(nDataStreams)
+ , m_maxNumPublish(maxNumPublish)
+ , m_rng(ndn::random::getRandomNumberEngine())
+ , m_rangeUniformRandom(0, 60000)
+ {
+ // Add user prefixes and schedule updates for them
+ for (int i = 0; i < m_nDataStreams; i++) {
+ ndn::Name updateName(userPrefix + "-" + ndn::to_string(i));
+
+ // Add the user prefix to the producer
+ // Note that this does not add the already added userPrefix-0 in the constructor
+ m_producer.addUserNode(updateName);
+
+ // Each user prefix is updated at random interval between 0 and 60 second
+ m_scheduler.scheduleEvent(ndn::time::milliseconds(m_rangeUniformRandom(m_rng)),
+ [this, updateName] {
+ doUpdate(updateName);
+ });
+ }
+ }
+
+ void
+ run()
+ {
+ m_face.processEvents();
+ }
+
+private:
+ void
+ doUpdate(const ndn::Name& updateName)
+ {
+ // Publish an update to this user prefix
+ m_producer.publishName(updateName);
+
+ uint64_t seqNo = m_producer.getSeqNo(updateName).value();
+ NDN_LOG_INFO("Publish: " << updateName << "/" << seqNo);
+
+ if (seqNo < m_maxNumPublish) {
+ // Schedule the next update for this user prefix b/w 0 and 60 seconds
+ m_scheduler.scheduleEvent(ndn::time::milliseconds(m_rangeUniformRandom(m_rng)),
+ [this, updateName] {
+ doUpdate(updateName);
+ });
+ }
+ }
+
+private:
+ ndn::Face m_face;
+ ndn::util::Scheduler m_scheduler;
+
+ psync::PartialProducer m_producer;
+
+ int m_nDataStreams;
+ uint64_t m_maxNumPublish;
+
+ ndn::random::RandomNumberEngine& m_rng;
+ std::uniform_int_distribution<int> m_rangeUniformRandom;
+};
+
+int
+main(int argc, char* argv[])
+{
+ if (argc != 5) {
+ std::cout << "usage: " << argv[0] << " <sync-prefix> <user-prefix> "
+ << "<number-of-user-prefixes> <max-number-of-updates-per-user-prefix>"
+ << std::endl;
+ return 1;
+ }
+
+ try {
+ PSyncPartialProducer producer(argv[1], argv[2], std::stoi(argv[3]), std::stoi(argv[4]));
+ producer.run();
+ }
+ catch (const std::exception& e) {
+ NDN_LOG_ERROR(e.what());
+ }
+}
\ No newline at end of file
diff --git a/examples/wscript b/examples/wscript
new file mode 100644
index 0000000..c737d81
--- /dev/null
+++ b/examples/wscript
@@ -0,0 +1,12 @@
+# -*- Mode: python; py-indent-offset: 4; indent-tabs-mode: nil; coding: utf-8; -*-
+
+top = '..'
+
+def build(bld):
+ # List all .cpp files (whole example in one .cpp)
+ for ex in bld.path.ant_glob('*.cpp'):
+ name = ex.change_ext('').path_from(bld.path.get_bld())
+ bld.program(name='example-%s' % name,
+ target='psync-%s' % name,
+ source=[ex],
+ use='PSync')
\ No newline at end of file