From 1973cdc4e622621e8e034f083794e922a1f387f4 Mon Sep 17 00:00:00 2001 From: "bea@american.lindenlab.com" Date: Thu, 3 Dec 2009 08:47:59 -0800 Subject: Add Doxygen comments --- indra/llplugin/llpluginmessage.cpp | 160 ++++++++++++++++++++++++++++++++++++- indra/llplugin/llpluginmessage.h | 10 +++ 2 files changed, 169 insertions(+), 1 deletion(-) (limited to 'indra/llplugin') diff --git a/indra/llplugin/llpluginmessage.cpp b/indra/llplugin/llpluginmessage.cpp index 34e02c356e..d06f3cefa0 100644 --- a/indra/llplugin/llpluginmessage.cpp +++ b/indra/llplugin/llpluginmessage.cpp @@ -37,31 +37,57 @@ #include "llsdserialize.h" #include "u64.h" +/** + * Constructor. + */ LLPluginMessage::LLPluginMessage() { } +/** + * Constructor. + * + * @param[in] p Existing message + */ LLPluginMessage::LLPluginMessage(const LLPluginMessage &p) { mMessage = p.mMessage; } +/** + * Constructor. + * + * @param[in] message_class Message class + * @param[in] message_name Message name + */ LLPluginMessage::LLPluginMessage(const std::string &message_class, const std::string &message_name) { setMessage(message_class, message_name); } +/** + * Destructor. + */ LLPluginMessage::~LLPluginMessage() { } +/** + * Reset all internal state. + */ void LLPluginMessage::clear() { mMessage = LLSD::emptyMap(); mMessage["params"] = LLSD::emptyMap(); } +/** + * Sets the message class and name. Also has the side-effect of clearing any key-value pairs in the message. + * + * @param[in] message_class Message class + * @param[in] message_name Message name + */ void LLPluginMessage::setMessage(const std::string &message_class, const std::string &message_name) { clear(); @@ -69,21 +95,45 @@ void LLPluginMessage::setMessage(const std::string &message_class, const std::st mMessage["name"] = message_name; } +/** + * Sets a key/value pair in the message, where the value is a string. + * + * @param[in] key Key + * @param[in] value String value + */ void LLPluginMessage::setValue(const std::string &key, const std::string &value) { mMessage["params"][key] = value; } +/** + * Sets a key/value pair in the message, where the value is LLSD. + * + * @param[in] key Key + * @param[in] value LLSD value + */ void LLPluginMessage::setValueLLSD(const std::string &key, const LLSD &value) { mMessage["params"][key] = value; } +/** + * Sets a key/value pair in the message, where the value is signed 32-bit. + * + * @param[in] key Key + * @param[in] value 32-bit signed value + */ void LLPluginMessage::setValueS32(const std::string &key, S32 value) { mMessage["params"][key] = value; } +/** + * Sets a key/value pair in the message, where the value is unsigned 32-bit. The value is stored as a string beginning with "0x". + * + * @param[in] key Key + * @param[in] value 32-bit unsigned value + */ void LLPluginMessage::setValueU32(const std::string &key, U32 value) { std::stringstream temp; @@ -91,16 +141,34 @@ void LLPluginMessage::setValueU32(const std::string &key, U32 value) setValue(key, temp.str()); } +/** + * Sets a key/value pair in the message, where the value is a bool. + * + * @param[in] key Key + * @param[in] value Boolean value + */ void LLPluginMessage::setValueBoolean(const std::string &key, bool value) { mMessage["params"][key] = value; } +/** + * Sets a key/value pair in the message, where the value is a double. + * + * @param[in] key Key + * @param[in] value Boolean value + */ void LLPluginMessage::setValueReal(const std::string &key, F64 value) { mMessage["params"][key] = value; } +/** + * Sets a key/value pair in the message, where the value is a pointer. The pointer is stored as a string. + * + * @param[in] key Key + * @param[in] value Pointer value + */ void LLPluginMessage::setValuePointer(const std::string &key, void* value) { std::stringstream temp; @@ -109,16 +177,33 @@ void LLPluginMessage::setValuePointer(const std::string &key, void* value) setValue(key, temp.str()); } +/** + * Gets the message class. + * + * @return Message class + */ std::string LLPluginMessage::getClass(void) const { return mMessage["class"]; } +/** + * Gets the message name. + * + * @return Message name + */ std::string LLPluginMessage::getName(void) const { return mMessage["name"]; } +/** + * Returns true if the specified key exists in this message (useful for optional parameters). + * + * @param[in] key Key + * + * @return True if key exists, false otherwise. + */ bool LLPluginMessage::hasValue(const std::string &key) const { bool result = false; @@ -131,6 +216,13 @@ bool LLPluginMessage::hasValue(const std::string &key) const return result; } +/** + * Gets the value of a key as a string. If the key does not exist, an empty string will be returned. + * + * @param[in] key Key + * + * @return String value of key if key exists, empty string if key does not exist. + */ std::string LLPluginMessage::getValue(const std::string &key) const { std::string result; @@ -143,6 +235,13 @@ std::string LLPluginMessage::getValue(const std::string &key) const return result; } +/** + * Gets the value of a key as LLSD. If the key does not exist, a null LLSD will be returned. + * + * @param[in] key Key + * + * @return LLSD value of key if key exists, null LLSD if key does not exist. + */ LLSD LLPluginMessage::getValueLLSD(const std::string &key) const { LLSD result; @@ -155,6 +254,13 @@ LLSD LLPluginMessage::getValueLLSD(const std::string &key) const return result; } +/** + * Gets the value of a key as signed 32-bit int. If the key does not exist, 0 will be returned. + * + * @param[in] key Key + * + * @return Signed 32-bit int value of key if key exists, 0 if key does not exist. + */ S32 LLPluginMessage::getValueS32(const std::string &key) const { S32 result = 0; @@ -167,6 +273,13 @@ S32 LLPluginMessage::getValueS32(const std::string &key) const return result; } +/** + * Gets the value of a key as unsigned 32-bit int. If the key does not exist, 0 will be returned. + * + * @param[in] key Key + * + * @return Unsigned 32-bit int value of key if key exists, 0 if key does not exist. + */ U32 LLPluginMessage::getValueU32(const std::string &key) const { U32 result = 0; @@ -181,6 +294,13 @@ U32 LLPluginMessage::getValueU32(const std::string &key) const return result; } +/** + * Gets the value of a key as a bool. If the key does not exist, false will be returned. + * + * @param[in] key Key + * + * @return Boolean value of key if it exists, false otherwise. + */ bool LLPluginMessage::getValueBoolean(const std::string &key) const { bool result = false; @@ -193,6 +313,13 @@ bool LLPluginMessage::getValueBoolean(const std::string &key) const return result; } +/** + * Gets the value of a key as a double. If the key does not exist, 0 will be returned. + * + * @param[in] key Key + * + * @return Value as a double if key exists, 0 otherwise. + */ F64 LLPluginMessage::getValueReal(const std::string &key) const { F64 result = 0.0f; @@ -205,6 +332,13 @@ F64 LLPluginMessage::getValueReal(const std::string &key) const return result; } +/** + * Gets the value of a key as a pointer. If the key does not exist, NULL will be returned. + * + * @param[in] key Key + * + * @return Pointer value if key exists, NULL otherwise. + */ void* LLPluginMessage::getValuePointer(const std::string &key) const { void* result = NULL; @@ -219,6 +353,11 @@ void* LLPluginMessage::getValuePointer(const std::string &key) const return result; } +/** + * Flatten the message into a string. + * + * @return Message as a string. + */ std::string LLPluginMessage::generate(void) const { std::ostringstream result; @@ -230,7 +369,11 @@ std::string LLPluginMessage::generate(void) const return result.str(); } - +/** + * Parse an incoming message into component parts. Clears all existing state before starting the parse. + * + * @return Returns -1 on failure, otherwise returns the number of key/value pairs in the incoming message. + */ int LLPluginMessage::parse(const std::string &message) { // clear any previous state @@ -255,16 +398,31 @@ LLPluginMessageDispatcher::~LLPluginMessageDispatcher() } +/** + * Add a message listener. TODO:DOC need more info on what uses this. when are multiple listeners needed? + * + * @param[in] listener Message listener + */ void LLPluginMessageDispatcher::addPluginMessageListener(LLPluginMessageListener *listener) { mListeners.insert(listener); } +/** + * Remove a message listener. + * + * @param[in] listener Message listener + */ void LLPluginMessageDispatcher::removePluginMessageListener(LLPluginMessageListener *listener) { mListeners.erase(listener); } +/** + * Distribute a message to all message listeners. + * + * @param[in] message Message + */ void LLPluginMessageDispatcher::dispatchPluginMessage(const LLPluginMessage &message) { for (listener_set_t::iterator it = mListeners.begin(); diff --git a/indra/llplugin/llpluginmessage.h b/indra/llplugin/llpluginmessage.h index 99f8d1194f..e00022a245 100644 --- a/indra/llplugin/llpluginmessage.h +++ b/indra/llplugin/llpluginmessage.h @@ -104,6 +104,9 @@ private: }; +/** + * @brief Listens for plugin messages. + */ class LLPluginMessageListener { public: @@ -112,6 +115,11 @@ public: }; +/** + * @brief Dispatcher for plugin messages. + * + * Manages the set of plugin message listeners and distributes messages to plugin message listeners. + */ class LLPluginMessageDispatcher { public: @@ -122,7 +130,9 @@ public: protected: void dispatchPluginMessage(const LLPluginMessage &message); + /** A set of message listeners. */ typedef std::set listener_set_t; + /** The set of message listeners. */ listener_set_t mListeners; }; -- cgit v1.2.3 From 67d051e78cb9f7d1ba670b647229ac9974fb7896 Mon Sep 17 00:00:00 2001 From: "bea@american.lindenlab.com" Date: Fri, 4 Dec 2009 13:28:39 -0800 Subject: Adding Doxygen comments --- indra/llplugin/llplugininstance.cpp | 28 +++++++++++++++++++++++++++- indra/llplugin/llplugininstance.h | 16 ++++++++++++---- 2 files changed, 39 insertions(+), 5 deletions(-) (limited to 'indra/llplugin') diff --git a/indra/llplugin/llplugininstance.cpp b/indra/llplugin/llplugininstance.cpp index 16ba492669..bb25475a59 100644 --- a/indra/llplugin/llplugininstance.cpp +++ b/indra/llplugin/llplugininstance.cpp @@ -37,13 +37,21 @@ #include "llapr.h" -//virtual +/** Virtual destructor. */ LLPluginInstanceMessageListener::~LLPluginInstanceMessageListener() { } +/** + * Name of plugin init function. TODO:DOC need to describe how it's used? + */ const char *LLPluginInstance::PLUGIN_INIT_FUNCTION_NAME = "LLPluginInitEntryPoint"; +/** + * Constructor. + * + * @param[in] owner Plugin instance. TODO:DOC is this a good description? + */ LLPluginInstance::LLPluginInstance(LLPluginInstanceMessageListener *owner) : mDSOHandle(NULL), mPluginUserData(NULL), @@ -52,6 +60,9 @@ LLPluginInstance::LLPluginInstance(LLPluginInstanceMessageListener *owner) : mOwner = owner; } +/** + * Destructor. + */ LLPluginInstance::~LLPluginInstance() { if(mDSOHandle != NULL) @@ -61,6 +72,12 @@ LLPluginInstance::~LLPluginInstance() } } +/** + * Dynamically loads the plugin and runs the plugin's init function. + * + * @param[in] plugin_file Name of plugin dll/dylib/so. TODO:DOC is this correct? see .h + * @return 0 if successful, APR error code or error code from the plugin's init function on failure. + */ int LLPluginInstance::load(std::string &plugin_file) { pluginInitFunction init_function = NULL; @@ -102,6 +119,11 @@ int LLPluginInstance::load(std::string &plugin_file) return (int)result; } +/** + * Sends a message to the plugin. + * + * @param[in] message Message + */ void LLPluginInstance::sendMessage(const std::string &message) { if(mPluginSendMessageFunction) @@ -115,6 +137,10 @@ void LLPluginInstance::sendMessage(const std::string &message) } } +/** + * Idle. TODO:DOC what's the purpose of this? + * + */ void LLPluginInstance::idle(void) { } diff --git a/indra/llplugin/llplugininstance.h b/indra/llplugin/llplugininstance.h index 02936f65fb..3a18d09172 100644 --- a/indra/llplugin/llplugininstance.h +++ b/indra/llplugin/llplugininstance.h @@ -60,19 +60,27 @@ public: // Sends a message to the plugin. void sendMessage(const std::string &message); + // TODO:DOC is this comment obsolete? can't find "send_count" anywhere in indra tree. // send_count is the maximum number of message to process from the send queue. If negative, it will drain the queue completely. // The receive queue is always drained completely. // Returns the total number of messages processed from both queues. void idle(void); - // this is the signature of the "send a message" function. - // message_string is a null-terminated C string - // user_data is the opaque reference that the callee supplied during setup. + /** The signature of the function for sending a message from plugin to plugin loader shell. + * + * @param[in] message_string Null-terminated C string + * @param[in] user_data The opaque reference that the callee supplied during setup. + */ typedef void (*sendMessageFunction) (const char *message_string, void **user_data); - // signature of the plugin init function + /** The signature of the plugin init function. TODO:DOC check direction (pluging loader shell to plugin?) + * + * @param[in] host_user_data Data from plugin loader shell. + * @param[in] plugin_send_function Function for sending from the plugin loader shell to plugin. + */ typedef int (*pluginInitFunction) (sendMessageFunction host_send_func, void *host_user_data, sendMessageFunction *plugin_send_func, void **plugin_user_data); + /** Name of plugin init function */ static const char *PLUGIN_INIT_FUNCTION_NAME; private: -- cgit v1.2.3 From 13eeba25d8573d0bb9ec6d19e5949a676ff546a2 Mon Sep 17 00:00:00 2001 From: "bea@american.lindenlab.com" Date: Fri, 4 Dec 2009 14:37:50 -0800 Subject: Fix some missing Doxygen comments --- indra/llplugin/llplugininstance.cpp | 9 +++++++-- indra/llplugin/llplugininstance.h | 8 +++++++- indra/llplugin/llpluginmessage.cpp | 6 ++++++ indra/llplugin/llpluginmessage.h | 8 +++++--- 4 files changed, 25 insertions(+), 6 deletions(-) (limited to 'indra/llplugin') diff --git a/indra/llplugin/llplugininstance.cpp b/indra/llplugin/llplugininstance.cpp index bb25475a59..44e3b4950f 100644 --- a/indra/llplugin/llplugininstance.cpp +++ b/indra/llplugin/llplugininstance.cpp @@ -43,14 +43,14 @@ LLPluginInstanceMessageListener::~LLPluginInstanceMessageListener() } /** - * Name of plugin init function. TODO:DOC need to describe how it's used? + * TODO:DOC describe how it's used */ const char *LLPluginInstance::PLUGIN_INIT_FUNCTION_NAME = "LLPluginInitEntryPoint"; /** * Constructor. * - * @param[in] owner Plugin instance. TODO:DOC is this a good description? + * @param[in] owner Plugin instance. TODO:DOC is this a good description of what "owner" is? */ LLPluginInstance::LLPluginInstance(LLPluginInstanceMessageListener *owner) : mDSOHandle(NULL), @@ -154,6 +154,11 @@ void LLPluginInstance::staticReceiveMessage(const char *message_string, void **u self->receiveMessage(message_string); } +/** + * Plugin receives message from plugin loader shell. + * + * @param[in] message_string Message + */ void LLPluginInstance::receiveMessage(const char *message_string) { if(mOwner) diff --git a/indra/llplugin/llplugininstance.h b/indra/llplugin/llplugininstance.h index 3a18d09172..c11d5ab5d4 100644 --- a/indra/llplugin/llplugininstance.h +++ b/indra/llplugin/llplugininstance.h @@ -1,6 +1,5 @@ /** * @file llplugininstance.h - * @brief LLPluginInstance handles loading the dynamic library of a plugin and setting up its entry points for message passing. * * @cond * $LicenseInfo:firstyear=2008&license=viewergpl$ @@ -39,13 +38,20 @@ #include "apr_dso.h" +/** + * @brief LLPluginInstanceMessageListener receives messages sent from the plugin loader shell to the plugin. + */ class LLPluginInstanceMessageListener { public: virtual ~LLPluginInstanceMessageListener(); + /** Plugin receives message from plugin loader shell. */ virtual void receivePluginMessage(const std::string &message) = 0; }; +/** + * @brief LLPluginInstance handles loading the dynamic library of a plugin and setting up its entry points for message passing. + */ class LLPluginInstance { LOG_CLASS(LLPluginInstance); diff --git a/indra/llplugin/llpluginmessage.cpp b/indra/llplugin/llpluginmessage.cpp index d06f3cefa0..f76d848a70 100644 --- a/indra/llplugin/llpluginmessage.cpp +++ b/indra/llplugin/llpluginmessage.cpp @@ -387,12 +387,18 @@ int LLPluginMessage::parse(const std::string &message) } +/** + * Destructor + */ LLPluginMessageListener::~LLPluginMessageListener() { // TODO: should listeners have a way to ensure they're removed from dispatcher lists when deleted? } +/** + * Destructor + */ LLPluginMessageDispatcher::~LLPluginMessageDispatcher() { diff --git a/indra/llplugin/llpluginmessage.h b/indra/llplugin/llpluginmessage.h index e00022a245..cbd31e0964 100644 --- a/indra/llplugin/llpluginmessage.h +++ b/indra/llplugin/llpluginmessage.h @@ -1,6 +1,5 @@ /** * @file llpluginmessage.h - * @brief LLPluginMessage encapsulates the serialization/deserialization of messages passed to and from plugins. * * @cond * $LicenseInfo:firstyear=2008&license=viewergpl$ @@ -36,7 +35,9 @@ #include "llsd.h" - +/** + * @brief LLPluginMessage encapsulates the serialization/deserialization of messages passed to and from plugins. + */ class LLPluginMessage { LOG_CLASS(LLPluginMessage); @@ -105,12 +106,13 @@ private: }; /** - * @brief Listens for plugin messages. + * @brief Listener for plugin messages. */ class LLPluginMessageListener { public: virtual ~LLPluginMessageListener(); + /** Plugin receives message from plugin loader shell. */ virtual void receivePluginMessage(const LLPluginMessage &message) = 0; }; -- cgit v1.2.3 From 0bf7917ae848388a3e1bc6ad13e300880fed12d0 Mon Sep 17 00:00:00 2001 From: "bea@american.lindenlab.com" Date: Wed, 9 Dec 2009 12:52:27 -0800 Subject: Added Doxygen comments --- indra/llplugin/llpluginsharedmemory.cpp | 12 +++++++- indra/llplugin/llpluginsharedmemory.h | 53 +++++++++++++++++++++++++++++++-- 2 files changed, 62 insertions(+), 3 deletions(-) (limited to 'indra/llplugin') diff --git a/indra/llplugin/llpluginsharedmemory.cpp b/indra/llplugin/llpluginsharedmemory.cpp index 3c69a69d28..9c18b410c7 100644 --- a/indra/llplugin/llpluginsharedmemory.cpp +++ b/indra/llplugin/llpluginsharedmemory.cpp @@ -1,6 +1,6 @@ /** * @file llpluginsharedmemory.cpp - * @brief LLPluginSharedMemory manages a shared memory segment for use by the LLPlugin API. + * LLPluginSharedMemory manages a shared memory segment for use by the LLPlugin API. * * @cond * $LicenseInfo:firstyear=2008&license=viewergpl$ @@ -96,6 +96,10 @@ std::string LLPluginSharedMemory::createName(void) return newname.str(); } +/** + * @brief LLPluginSharedMemoryImpl is the platform-dependent implementation of LLPluginSharedMemory. TODO:DOC is this necessary/sufficient? kinda obvious. + * + */ class LLPluginSharedMemoryPlatformImpl { public: @@ -112,6 +116,9 @@ public: }; +/** + * Constructor. Creates a shared memory segment. + */ LLPluginSharedMemory::LLPluginSharedMemory() { mSize = 0; @@ -121,6 +128,9 @@ LLPluginSharedMemory::LLPluginSharedMemory() mImpl = new LLPluginSharedMemoryPlatformImpl; } +/** + * Destructor. Uses destroy() and detach() to ensure shared memory segment is cleaned up. + */ LLPluginSharedMemory::~LLPluginSharedMemory() { if(mNeedsDestroy) diff --git a/indra/llplugin/llpluginsharedmemory.h b/indra/llplugin/llpluginsharedmemory.h index 4014620c52..00c54ef08c 100644 --- a/indra/llplugin/llpluginsharedmemory.h +++ b/indra/llplugin/llpluginsharedmemory.h @@ -1,6 +1,5 @@ /** * @file llpluginsharedmemory.h - * @brief LLPluginSharedMemory manages a shared memory segment for use by the LLPlugin API. * * @cond * $LicenseInfo:firstyear=2008&license=viewergpl$ @@ -36,6 +35,10 @@ class LLPluginSharedMemoryPlatformImpl; +/** + * @brief LLPluginSharedMemory manages a shared memory segment for use by the LLPlugin API. + * + */ class LLPluginSharedMemory { LOG_CLASS(LLPluginSharedMemory); @@ -46,16 +49,62 @@ public: // Parent will use create/destroy, child will use attach/detach. // Message transactions will ensure child attaches after parent creates and detaches before parent destroys. - // create() implicitly creates a name for the segment which is guaranteed to be unique on the host at the current time. + /** + * Creates a shared memory segment, with a name which is guaranteed to be unique on the host at the current time. Used by parent. + * Message transactions will (? TODO:DOC - should? must?) ensure child attaches after parent creates and detaches before parent destroys. + * + * @param[in] size Shared memory size in TODO:DOC units = bytes?. + * + * @return False for failure, true for success. + */ bool create(size_t size); + /** + * Destroys a shared memory segment. Used by parent. + * Message transactions will (? TODO:DOC - should? must?) ensure child attaches after parent creates and detaches before parent destroys. + * + * @return True. TODO:DOC - always returns true. Is this the intended behavior? + */ bool destroy(void); + /** + * Creates and attaches a name to a shared memory segment. TODO:DOC what's the difference between attach() and create()? + * + * @param[in] name Name to attach to memory segment + * @param[in] size Size of memory segment TODO:DOC in bytes? + * + * @return False on failure, true otherwise. + */ bool attach(const std::string &name, size_t size); + /** + * Detaches shared memory segment. + * + * @return False on failure, true otherwise. + */ bool detach(void); + /** + * Checks if shared memory is mapped to a non-null address. + * + * @return True if memory address is non-null, false otherwise. + */ bool isMapped(void) const { return (mMappedAddress != NULL); }; + /** + * Get pointer to shared memory. + * + * @return Pointer to shared memory. + */ void *getMappedAddress(void) const { return mMappedAddress; }; + /** + * Get size of shared memory. + * + * @return Size of shared memory in bytes. TODO:DOC are bytes the correct unit? + */ size_t getSize(void) const { return mSize; }; + /** + * Get name of shared memory. + * + * @return Name of shared memory. + */ std::string getName() const { return mName; }; private: -- cgit v1.2.3