From 063d69ed96f6cf036e0a9fbd68877fd2aa4cef40 Mon Sep 17 00:00:00 2001 From: Gunnar Beutner Date: Fri, 14 Sep 2012 14:41:17 +0200 Subject: [PATCH] Added missing doc strings. --- lib/base/application.cpp | 16 ++++++++++++++++ lib/base/component.cpp | 3 +++ lib/base/dictionary.cpp | 3 +++ lib/base/event.cpp | 19 +++++++++++++++++++ lib/base/logger.cpp | 10 ++++++++++ lib/base/object.cpp | 13 +++++++++++++ lib/base/process.cpp | 5 +++++ lib/base/socket.cpp | 25 +++++++++++++++++++++++++ lib/base/tcpclient.cpp | 6 ++++++ lib/base/value.cpp | 31 +++++++++++++++++++++++++++++++ 10 files changed, 131 insertions(+) diff --git a/lib/base/application.cpp b/lib/base/application.cpp index 4f5be7e2e..66a337b17 100644 --- a/lib/base/application.cpp +++ b/lib/base/application.cpp @@ -212,11 +212,19 @@ bool Application::IsDebugging(void) return m_Debugging; } +/** + * Checks whether we're currently on the main thread. + * + * @returns true if this is the main thread, false otherwise + */ bool Application::IsMainThread(void) { return (boost::this_thread::get_id() == m_MainThreadID); } +/** + * Sets the main thread to the currently running thread. + */ void Application::SetMainThread(void) { m_MainThreadID = boost::this_thread::get_id(); @@ -313,6 +321,11 @@ int Application::Run(int argc, char **argv) return result; } +/** + * Grabs the PID file lock and updates the PID. + * + * @param filename The name of the PID file. + */ void Application::UpdatePidFile(const String& filename) { ClosePidFile(); @@ -344,6 +357,9 @@ void Application::UpdatePidFile(const String& filename) fflush(m_PidFile); } +/** + * Closes the PID file. Does nothing if the PID file is not currently open. + */ void Application::ClosePidFile(void) { if (m_PidFile != NULL) diff --git a/lib/base/component.cpp b/lib/base/component.cpp index c28847d84..70652aab9 100644 --- a/lib/base/component.cpp +++ b/lib/base/component.cpp @@ -99,6 +99,9 @@ Component::Component(const Dictionary::Ptr& properties) m_Impl = impl; } +/** + * Destructor for the Component class. + */ Component::~Component(void) { if (m_Impl) diff --git a/lib/base/dictionary.cpp b/lib/base/dictionary.cpp index 6fcfeaf59..e9442b183 100644 --- a/lib/base/dictionary.cpp +++ b/lib/base/dictionary.cpp @@ -22,6 +22,9 @@ using namespace icinga; +/** + * Compares the keys of dictionary keys using the less operator. + */ struct DictionaryKeyLessComparer { bool operator()(const pair& a, const char *b) diff --git a/lib/base/event.cpp b/lib/base/event.cpp index d72b184ae..803662e86 100644 --- a/lib/base/event.cpp +++ b/lib/base/event.cpp @@ -25,14 +25,27 @@ vector Event::m_Events; condition_variable Event::m_EventAvailable; boost::mutex Event::m_Mutex; +/** + * Constructor for the Event class + * + * @param callback The callback function for the new event object. + */ Event::Event(const Event::Callback& callback) : m_Callback(callback) { } +/** + * Waits for events using the specified timeout value and processes + * them. + * + * @param wait_until The wait timeout. + */ void Event::ProcessEvents(const system_time& wait_until) { vector events; + assert(Application::IsMainThread()); + { boost::mutex::scoped_lock lock(m_Mutex); @@ -59,6 +72,12 @@ void Event::ProcessEvents(const system_time& wait_until) } } +/** + * Appends an event to the event queue. Events will be processed in FIFO + * order on the main thread. + * + * @param callback The callback function for the event. + */ void Event::Post(const Event::Callback& callback) { if (Application::IsMainThread()) { diff --git a/lib/base/logger.cpp b/lib/base/logger.cpp index edd2a3d7c..ff3c5bd4a 100644 --- a/lib/base/logger.cpp +++ b/lib/base/logger.cpp @@ -126,6 +126,11 @@ void Logger::ForwardLogEntry(const LogEntry& entry) StreamLogger::ProcessLogEntry(std::cout, entry); } +/** + * Converts a severity enum value to a string. + * + * @param severity The severity value. + */ String Logger::SeverityToString(LogSeverity severity) { switch (severity) { @@ -142,6 +147,11 @@ String Logger::SeverityToString(LogSeverity severity) } } +/** + * Converts a string to a severity enum value. + * + * @param severity The severity. + */ LogSeverity Logger::StringToSeverity(const String& severity) { if (severity == "debug") diff --git a/lib/base/object.cpp b/lib/base/object.cpp index da68ed0fa..d0e221f4e 100644 --- a/lib/base/object.cpp +++ b/lib/base/object.cpp @@ -69,18 +69,31 @@ void Object::ClearHeldObjects(void) m_HeldObjects.clear(); } +/** + * Returns a reference-counted pointer to this object. + * + * @returns A shared_ptr object that points to this object + */ Object::SharedPtrHolder Object::GetSelf(void) { return Object::SharedPtrHolder(shared_from_this()); } #ifdef _DEBUG +/** + * Retrieves the number of currently alive objects. + * + * @returns The number of alive objects. + */ int Object::GetAliveObjects(void) { boost::mutex::scoped_lock lock(m_Mutex); return m_AliveObjects.size(); } +/** + * Dumps a memory histogram to the "dictionaries.dump" file. + */ void Object::PrintMemoryProfile(void) { map types; diff --git a/lib/base/process.cpp b/lib/base/process.cpp index 1a8e8aed8..0686d0c79 100644 --- a/lib/base/process.cpp +++ b/lib/base/process.cpp @@ -212,6 +212,11 @@ bool Process::RunTask(void) return false; } +/** + * Retrives the stdout file descriptor for the child process. + * + * @returns The stdout file descriptor. + */ int Process::GetFD(void) const { return fileno(m_FP); diff --git a/lib/base/socket.cpp b/lib/base/socket.cpp index db8737fcc..dd6240e39 100644 --- a/lib/base/socket.cpp +++ b/lib/base/socket.cpp @@ -37,6 +37,9 @@ Socket::~Socket(void) CloseInternal(true); } +/** + * Starts I/O processing for this socket. + */ void Socket::Start(void) { assert(!m_ReadThread.joinable() && !m_WriteThread.joinable()); @@ -256,6 +259,10 @@ SocketException::SocketException(const String& message, int errorCode) SetMessage(msg.CStr()); } +/** + * Read thread procedure for sockets. This function waits until the + * socket is readable and processes inbound data. + */ void Socket::ReadThreadProc(void) { boost::mutex::scoped_lock lock(m_SocketMutex); @@ -310,6 +317,10 @@ void Socket::ReadThreadProc(void) } } +/** + * Write thread procedure for sockets. This function waits until the socket + * is writable and processes outbound data. + */ void Socket::WriteThreadProc(void) { boost::mutex::scoped_lock lock(m_SocketMutex); @@ -358,16 +369,30 @@ void Socket::WriteThreadProc(void) } } +/** + * Sets whether the socket is fully connected. + * + * @param connected Whether the socket is connected + */ void Socket::SetConnected(bool connected) { m_Connected = connected; } +/** + * Checks whether the socket is fully connected. + * + * @returns true if the socket is connected, false otherwise + */ bool Socket::IsConnected(void) const { return m_Connected; } +/** + * Checks whether an exception is available for this socket. Should be called + * by user-supplied handlers for the OnClosed signal. + */ void Socket::CheckException(void) { if (m_Exception) diff --git a/lib/base/tcpclient.cpp b/lib/base/tcpclient.cpp index 6680763d7..c21a438cd 100644 --- a/lib/base/tcpclient.cpp +++ b/lib/base/tcpclient.cpp @@ -102,6 +102,9 @@ void TcpClient::Connect(const String& node, const String& service) throw_exception(runtime_error("Could not create a suitable socket.")); } +/** + * Processes data that is available for this socket. + */ void TcpClient::HandleWritable(void) { int rc; @@ -180,6 +183,9 @@ void TcpClient::Write(const void *buffer, size_t count) m_SendQueue->Write(buffer, count); } +/** + * Processes data that can be written for this socket. + */ void TcpClient::HandleReadable(void) { if (!IsConnected()) { diff --git a/lib/base/value.cpp b/lib/base/value.cpp index 90446c831..f29be13c4 100644 --- a/lib/base/value.cpp +++ b/lib/base/value.cpp @@ -34,16 +34,31 @@ bool Value::IsEmpty(void) const return (m_Value.type() == typeid(boost::blank)); } +/** + * Checks whether the variant is scalar (i.e. not an object and not empty). + * + * @returns true if the variant is scalar, false otherwise. + */ bool Value::IsScalar(void) const { return !IsEmpty() && !IsObject(); } +/** + * Checks whether the variant is a non-null object. + * + * @returns true if the variant is a non-null object, false otherwise. + */ bool Value::IsObject(void) const { return !IsEmpty() && (m_Value.type() == typeid(Object::Ptr)); } +/** + * Converts a JSON object into a variant. + * + * @param json The JSON object. + */ Value Value::FromJson(cJSON *json) { if (json->type == cJSON_Number) @@ -62,6 +77,11 @@ Value Value::FromJson(cJSON *json) throw_exception(invalid_argument("Unsupported JSON type.")); } +/** + * Serializes a variant into a string. + * + * @returns A string representing this variant. + */ String Value::Serialize(void) const { cJSON *json = ToJson(); @@ -82,6 +102,11 @@ String Value::Serialize(void) const return result; } +/** + * Serializes the variant. + * + * @returns A JSON object representing this variant. + */ cJSON *Value::ToJson(void) const { if (m_Value.type() == typeid(long)) { @@ -105,6 +130,12 @@ cJSON *Value::ToJson(void) const } } +/** + * Deserializes the string representation of a variant. + * + * @params jsonString A JSON string obtained from Value::Serialize + * @returns The newly deserialized variant. + */ Value Value::Deserialize(const String& jsonString) { cJSON *json = cJSON_Parse(jsonString.CStr()); -- 2.40.0