docs: unregister prefixes instead of calling Face::shutdown
refs #4636
Change-Id: I15944bcb544bdbf0c253fe390c4ff459735d64a6
diff --git a/src/face.hpp b/src/face.hpp
index e5ccbba..23634f1 100644
--- a/src/face.hpp
+++ b/src/face.hpp
@@ -1,6 +1,6 @@
/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */
/*
- * Copyright (c) 2013-2017 Regents of the University of California.
+ * Copyright (C) 2013-2018 Regents of the University of California.
*
* This file is part of ndn-cxx library (NDN C++ library with eXperimental eXtensions).
*
@@ -190,7 +190,7 @@
Face(shared_ptr<Transport> transport, KeyChain& keyChain);
/**
- * @brief Create Face using given transport and IO service
+ * @brief Create Face using given transport and io_service
* @param transport the transport for lower layer communication. If nullptr,
* a default transport will be used.
* @param ioService the io_service that controls all IO operations
@@ -205,7 +205,7 @@
Face(shared_ptr<Transport> transport, boost::asio::io_service& ioService);
/**
- * @brief Create a new Face using given Transport and IO service
+ * @brief Create a new Face using given Transport and io_service
* @param transport the transport for lower layer communication. If nullptr,
* a default transport will be used.
* @param ioService the io_service that controls all IO operations
@@ -428,18 +428,24 @@
* @brief Process any data to receive or call timeout callbacks.
*
* This call will block forever (default timeout == 0) to process IO on the face.
- * To exit, one expected to call face.shutdown() from one of the callback methods.
+ * To exit cleanly on a producer, unset any Interest filters with unsetInterestFilter() and wait
+ * for processEvents() to return. To exit after an error, one can call shutdown().
+ * In consumer applications, processEvents() will return when all expressed Interests have been
+ * satisfied, Nacked, or timed out. To terminate earlier, a consumer application should call
+ * removePendingInterests() for all previously expressed and still-pending Interests.
*
- * If positive timeout is specified, then processEvents will exit after this timeout, if
- * not stopped earlier with face.shutdown() or when all active events finish. The call
+ * If a positive timeout is specified, then processEvents() will exit after this timeout, provided
+ * it is not stopped earlier with shutdown() or when all active events finish. processEvents()
* can be called repeatedly, if desired.
*
- * If negative timeout is specified, then processEvents will not block and process only
+ * If a negative timeout is specified, then processEvents will not block and will process only
* pending events.
*
* @param timeout maximum time to block the thread
* @param keepThread Keep thread in a blocked state (in event processing), even when
- * there are no outstanding events (e.g., no Interest/Data is expected)
+ * there are no outstanding events (e.g., no Interest/Data is expected).
+ * If timeout is zero and this parameter is true, the only way to stop
+ * processEvents() is to call shutdown().
*
* @note This may throw an exception for reading data or in the callback for processing
* the data. If you call this from an main event loop, you may want to catch and
@@ -459,14 +465,18 @@
*
* This method cancels all pending operations and closes connection to NDN Forwarder.
*
- * Note that this method does not stop IO service and if the same IO service is shared
- * between multiple Faces or with other IO objects (e.g., Scheduler).
+ * Note that this method does not stop the io_service if it is shared between multiple Faces or
+ * with other IO objects (e.g., Scheduler).
+ *
+ * @warning Calling this method could cause outgoing packets to be lost. Producers that shut down
+ * immediately after sending a Data packet should instead use unsetInterestFilter() to
+ * shut down cleanly.
*/
void
shutdown();
/**
- * @return reference to IO service object
+ * @return reference to io_service object
*/
boost::asio::io_service&
getIoService()
@@ -506,9 +516,9 @@
asyncShutdown();
private:
- /// the IO service owned by this Face, could be null
+ /// the io_service owned by this Face, could be null
unique_ptr<boost::asio::io_service> m_internalIoService;
- /// the IO service used by this Face
+ /// the io_service used by this Face
boost::asio::io_service& m_ioService;
shared_ptr<Transport> m_transport;