From 91800787ed74015272767752fe87387bc51f5d79 Mon Sep 17 00:00:00 2001 From: Brendan Chandler Date: Fri, 13 May 2022 13:48:46 -0500 Subject: [PATCH 1/2] Doxygen support for ipAddrToAsciiAsynchronous.h --- .../src/misc/ipAddrToAsciiAsynchronous.h | 100 ++++++++++++++++++ 1 file changed, 100 insertions(+) diff --git a/modules/libcom/src/misc/ipAddrToAsciiAsynchronous.h b/modules/libcom/src/misc/ipAddrToAsciiAsynchronous.h index c3cc3f2f2..9b67348eb 100644 --- a/modules/libcom/src/misc/ipAddrToAsciiAsynchronous.h +++ b/modules/libcom/src/misc/ipAddrToAsciiAsynchronous.h @@ -8,6 +8,55 @@ * in file LICENSE that is included with this distribution. \*************************************************************************/ +/** + * \file ipAddrToAsciiAsynchronous.h + * \brief Convert ip addresses to ASCII asynchronously + * + * ipAddrToAsciiEngine is the first class needed to convert an ipAddr to an + * ASCII address. From the engine, you can use createTransaction() to create a + * transaction object. The transaction object lets you attach callbacks and + * convert an address to ASCII. + * + * Example + * ------------- + * + * \code{.cpp} + * struct MyResult: ipAddrToAsciiCallBack + * { + * virtual void transactionComplete (char const * node) override + * { + * printf("Address is %s\n", node); + * } + * + * virtual void show(unsigned level) override const + * { + * printf("This is a MyResult class object."); + * } + * }; + * + * ipAddrToAsciiEngine & engine(ipAddrToAsciiEngine::allocate()); + * ipAddrToAsciiTransaction & trans(engine.createTransaction()); + * + * osiSockAddr addr; + * addr.ia.sin_family = AF_INET; + * addr.ia.sin_addr.s_addr = htonl(INADDR_LOOPBACK); + * addr.ia.sin_port = htons(8080); + * + * MyResult results; + * trans.ipAddrToAscii(addr, results); + * + * // Do other work and wait for results to finish. + * // Note that typically you would use an epicsEvent or similar to coordinate + * // making sure the result is ready from your callback. For this example, + * // we'll ignore that complexity and use a naive sleep call instead. + * sleep(2); + * + * + * trans.release(); + * engine.release(); + * \endcode + */ + /* * Author Jeffrey O. Hill * johill@lanl.gov @@ -19,28 +68,79 @@ #include "osiSock.h" #include "libComAPI.h" +/** \brief Users implement this virtual class to use ipAddrToAsciiTransaction + * + * In order to use ipAddrToAsciiTranaction, users should implement this virtual + * class to handle events that occur asynchronously while converting the IP + * address. + * + */ class LIBCOM_API ipAddrToAsciiCallBack { public: + /// Called once the ip address is converted to ASCII + /* + * \param pHostName The converted ASCII name */ virtual void transactionComplete ( const char * pHostName ) = 0; + + /// Called by the show() method of ipAddrToAsciiTransaction or + /// ipAddrToAsciiEngine when passed a level >= 1. virtual void show ( unsigned level ) const; + virtual ~ipAddrToAsciiCallBack () = 0; }; +/// Class which convert an ipAddr to ascii and call a user-supplied callback +/// when finished. class LIBCOM_API ipAddrToAsciiTransaction { public: + /// Destroy this transaction object and remove from the parent engine object virtual void release () = 0; + + /** \brief Convert an IP address to ascii, asynchronously + * + * \param osiSockAddr Reference to the address to convert + * \param ipAddrToAsciiCallBack Reference to the user supplied callbacks to call when the result is available + */ virtual void ipAddrToAscii ( const osiSockAddr &, ipAddrToAsciiCallBack & ) = 0; + + /** \brief Get the conversion address currently set + * \return Get the last (or current) address converted to ascii + */ virtual osiSockAddr address () const = 0; + + /* \brief Prints the converted IP address + * Prints to stdout + * + * \param level 0 prints basic info, greater than 0 prints information from the callback's show() method too + */ virtual void show ( unsigned level ) const = 0; protected: virtual ~ipAddrToAsciiTransaction () = 0; }; +/// Class which manages creating transactions for converting ipAddr's to ASCII class LIBCOM_API ipAddrToAsciiEngine { public: + /// Cancel any pending transactions and destroy this ipAddrToAsciiEngine object. virtual void release () = 0; + + /** \brief Create a new transaction object used to do IP address conversions + * \return The newly created transaction object + */ virtual ipAddrToAsciiTransaction & createTransaction () = 0; + + /* \brief Print information about this engine object and how many requests its processing + * + * Prints to stdout + * + * \param level 0 for basic information, 1 for extra info + */ virtual void show ( unsigned level ) const = 0; + + /** \brief Creates a new ipAddrToAsciiEngine to convert IP addresses + * + * \return Newly created engine object + */ static ipAddrToAsciiEngine & allocate (); protected: virtual ~ipAddrToAsciiEngine () = 0; From 9864f79d672983de3b0f94c46683dbf4457256e5 Mon Sep 17 00:00:00 2001 From: Brendan Chandler Date: Mon, 16 May 2022 13:06:36 -0500 Subject: [PATCH 2/2] Update doxygen for ipAddrToAsciiAsynchronous --- .../src/misc/ipAddrToAsciiAsynchronous.h | 57 ++++++++++++------- 1 file changed, 37 insertions(+), 20 deletions(-) diff --git a/modules/libcom/src/misc/ipAddrToAsciiAsynchronous.h b/modules/libcom/src/misc/ipAddrToAsciiAsynchronous.h index 9b67348eb..11af8361a 100644 --- a/modules/libcom/src/misc/ipAddrToAsciiAsynchronous.h +++ b/modules/libcom/src/misc/ipAddrToAsciiAsynchronous.h @@ -21,38 +21,48 @@ * ------------- * * \code{.cpp} - * struct MyResult: ipAddrToAsciiCallBack + * class ConvertIPAddr: ipAddrToAsciiCallBack * { + * ipAddrToAsciiTransaction & trans; + * + * public: + * epicsEvent complete; + * + * ConvertIPAddr(ipAddrToAsciiEngine & engine, osiSockAddr & addr): + * trans(engine.createTransaction()) + * { + * trans.ipAddrToAscii(addr, *this); + * } + * * virtual void transactionComplete (char const * node) override * { * printf("Address is %s\n", node); + * complete.signal(); * } * * virtual void show(unsigned level) override const * { - * printf("This is a MyResult class object."); + * printf("This is a ConvertIPAddr class object."); + * } + * + * virtual ~ConvertIPAddr() + * { + * trans.release(); * } * }; * * ipAddrToAsciiEngine & engine(ipAddrToAsciiEngine::allocate()); - * ipAddrToAsciiTransaction & trans(engine.createTransaction()); * * osiSockAddr addr; * addr.ia.sin_family = AF_INET; * addr.ia.sin_addr.s_addr = htonl(INADDR_LOOPBACK); * addr.ia.sin_port = htons(8080); * - * MyResult results; - * trans.ipAddrToAscii(addr, results); + * ConvertIPAddr result(engine, addr); * - * // Do other work and wait for results to finish. - * // Note that typically you would use an epicsEvent or similar to coordinate - * // making sure the result is ready from your callback. For this example, - * // we'll ignore that complexity and use a naive sleep call instead. - * sleep(2); + * // Do other work here before waiting on the result * - * - * trans.release(); + * result.complete.wait(2.0); * engine.release(); * \endcode */ @@ -98,17 +108,20 @@ public: /** \brief Convert an IP address to ascii, asynchronously * - * \param osiSockAddr Reference to the address to convert - * \param ipAddrToAsciiCallBack Reference to the user supplied callbacks to call when the result is available + * \note The ipAddrToAsciiCallBack referenced must remain valid until release() is called on this transaction. + * \param addrIn Reference to the address to convert + * \param cbIn Reference to the user supplied callbacks to call when the result is available */ - virtual void ipAddrToAscii ( const osiSockAddr &, ipAddrToAsciiCallBack & ) = 0; + virtual void ipAddrToAscii ( const osiSockAddr & addrIn, ipAddrToAsciiCallBack & cbIn ) = 0; /** \brief Get the conversion address currently set * \return Get the last (or current) address converted to ascii */ virtual osiSockAddr address () const = 0; - /* \brief Prints the converted IP address + /** + * \brief Prints the converted IP address + * * Prints to stdout * * \param level 0 prints basic info, greater than 0 prints information from the callback's show() method too @@ -124,12 +137,15 @@ public: /// Cancel any pending transactions and destroy this ipAddrToAsciiEngine object. virtual void release () = 0; - /** \brief Create a new transaction object used to do IP address conversions + /** + * \brief Create a new transaction object used to do IP address conversions + * \note Caller must release() the returned transaction * \return The newly created transaction object */ virtual ipAddrToAsciiTransaction & createTransaction () = 0; - /* \brief Print information about this engine object and how many requests its processing + /** + * \brief Print information about this engine object and how many requests its processing * * Prints to stdout * @@ -137,8 +153,9 @@ public: */ virtual void show ( unsigned level ) const = 0; - /** \brief Creates a new ipAddrToAsciiEngine to convert IP addresses - * + /** + * \brief Creates a new ipAddrToAsciiEngine to convert IP addresses + * \note Caller must release() this engine. * \return Newly created engine object */ static ipAddrToAsciiEngine & allocate ();