Documentation only, no functional change
Added copyrights and comments within headers
Change-Id: Iebb17ba34b82a6c80718ad32338105a5245e640c
Signed-off-by: Matthew Barth <msbarth@us.ibm.com>
diff --git a/src/actions.hpp b/src/actions.hpp
index e1f53ad..e5269d1 100644
--- a/src/actions.hpp
+++ b/src/actions.hpp
@@ -13,6 +13,14 @@
using namespace phosphor::logging;
+/**
+ * @brief An action to log an error with the given message
+ *
+ * @param[in] msg - The message to log
+ *
+ * @return Lambda function
+ * A lambda function to perform the log_error function
+ */
inline auto log_error(const char* msg)
{
return [=](auto&, auto&)
diff --git a/src/conditions.hpp b/src/conditions.hpp
index 54a6dc6..b613679 100644
--- a/src/conditions.hpp
+++ b/src/conditions.hpp
@@ -12,6 +12,22 @@
namespace condition
{
+/**
+ * @brief A condition used to trigger an action when a number of items are at
+ * or above a given value
+ * @details A given group of items is updated with their last known item
+ * value, which then the entire group is checked if there are a given number of
+ * them at or above a value which would cause the condition to be true
+ *
+ * @param[in] items - Group of items
+ * @param[in] path - Path of a item within the group
+ * @param[in] count - Number of items needed at or above value
+ * @param[in] value - Value of items to be at or above
+ *
+ * @return Lambda function
+ * A lambda function to determine if the number of items within the group
+ * are at or above the given value
+ */
template <typename T>
auto countAtOrAbove(Group& items, const char* path, size_t count, T&& value)
{
diff --git a/src/data_types.hpp b/src/data_types.hpp
index 49406ea..cbe6faf 100644
--- a/src/data_types.hpp
+++ b/src/data_types.hpp
@@ -13,14 +13,18 @@
class Monitor;
+/** @brief The possible item value types */
using Value = int64_t;
+/** @brief A list of what constructs a unique item and its value */
using Group = std::vector<std::tuple<std::string, Value>>;
+/** @brief A conditional function type for item(s) conditions */
using Condition = std::function<bool(sdbusplus::bus::bus&,
sdbusplus::message::message&,
Monitor&)>;
+/** @brief A void function type for actions based condition(s) */
using Action = std::function<void(sdbusplus::bus::bus&,
Monitor&)>;
diff --git a/src/events.hpp b/src/events.hpp
index b6de8de..684a0a8 100644
--- a/src/events.hpp
+++ b/src/events.hpp
@@ -9,9 +9,17 @@
namespace monitoring
{
+/**
+ * @class Event
+ * @brief An item monitoring triggered event
+ * @details An event with an associated list of conditions to check
+ */
class Event : public std::vector<Condition>
{
public:
+ /**
+ * @brief Types of triggers of the event
+ */
enum class Trigger
{
START,
@@ -25,6 +33,12 @@
Event& operator=(Event&&) = delete;
virtual ~Event() = default;
+ /**
+ * @brief Constructs an event with given conditions and trigger
+ *
+ * @param[in] conditions - Conditions for the event
+ * @param[in] t - Type of trigger of the event
+ */
Event(const std::vector<Condition>& conditions,
Trigger t) :
std::vector<Condition>(conditions),
@@ -33,6 +47,7 @@
// Nothing to do here
}
+ /** @brief Event trigger type */
Trigger trigger;
};
@@ -46,6 +61,11 @@
StartEvent& operator=(StartEvent&&) = delete;
~StartEvent() = default;
+ /**
+ * @brief Constructs a derived application started event
+ *
+ * @param[in] conditions - Conditions for the event
+ */
explicit StartEvent(const std::vector<Condition>& conditions) :
Event(conditions, Trigger::START)
{
@@ -63,6 +83,12 @@
SignalEvent& operator=(SignalEvent&&) = delete;
~SignalEvent() = default;
+ /**
+ * @brief Constructs a derived Dbus signal event
+ *
+ * @param[in] signature - Dbus object signature
+ * @param[in] conditions - Conditions for the event
+ */
SignalEvent(const char* signature,
const std::vector<Condition>& conditions) :
Event(conditions, Trigger::SIGNAL),
@@ -71,6 +97,7 @@
// Nothing to do here
}
+ /** @brief Dbus object signature */
const char* signature;
};
diff --git a/src/functor.cpp b/src/functor.cpp
index f4d2574..72ff65e 100644
--- a/src/functor.cpp
+++ b/src/functor.cpp
@@ -1,3 +1,18 @@
+/**
+ * Copyright © 2017 IBM Corporation
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
#include "functor.hpp"
#include <sdbusplus/bus.hpp>
#include <sdbusplus/message.hpp>
diff --git a/src/functor.hpp b/src/functor.hpp
index b3ad9a0..3faf39b 100644
--- a/src/functor.hpp
+++ b/src/functor.hpp
@@ -11,18 +11,39 @@
class Monitor;
+/**
+ * @brief Create a condition function object
+ *
+ * @param[in] condition - The condition being created
+ *
+ * @return - The created condition function object
+ */
template <typename T>
auto make_condition(T&& condition)
{
return Condition(std::forward<T>(condition));
}
+/**
+ * @brief Create an action function object
+ *
+ * @param[in] action - The action being created
+ *
+ * @return - The created action function object
+ */
template <typename T>
auto make_action(T&& action)
{
return Action(std::forward<T>(action));
}
+/**
+ * @struct Property Changed Condtion
+ * @brief A match filter functor to test Dbus property value changed signals
+ *
+ * @tparam T - The type of the property value
+ * @tparam U - The type of the condition
+ */
template <typename T, typename U>
struct PropertyChangedCondition
{
@@ -76,6 +97,12 @@
U _condition;
};
+/**
+ * @struct Property Condition Base
+ * @brief A match filter functor to test property values
+ * @details The base property condition struct that retrieves the property value
+ * for a property condition
+ */
struct PropertyConditionBase
{
PropertyConditionBase() = delete;
@@ -128,6 +155,13 @@
const char* _service;
};
+/**
+ * @struct Property Condtion
+ * @brief A match filter functor to test property values
+ *
+ * @tparam T - The type of the property value
+ * @tparam U - The type of the condition
+ */
template <typename T, typename U>
struct PropertyCondition final : public PropertyConditionBase
{
@@ -177,6 +211,16 @@
U _condition;
};
+/**
+ * @brief Used to process a Dbus property changed signal event
+ *
+ * @param[in] iface - Item value interface
+ * @param[in] property - Item value property
+ * @param[in] condition - Condition function to perform
+ *
+ * @tparam T - The type of the property
+ * @tparam U - The type of the condition
+ */
template <typename T, typename U>
auto propertySignal(const char* iface,
const char* property,
@@ -187,6 +231,18 @@
std::move(condition));
}
+/**
+ * @brief Used to process conditions on a start event
+ *
+ * @param[in] path - Item's Dbus path
+ * @param[in] iface - Item value interface
+ * @param[in] property - Item value property
+ * @param[in] condition - Condition function to perform
+ * @param[in] service - Service to lookup Dbus object
+ *
+ * @tparam T - The type of the property
+ * @tparam U - The type of the condition
+ */
template <typename T, typename U>
auto propertyStart(const char* path,
const char* iface,
diff --git a/src/main.cpp b/src/main.cpp
index 6d1a071..a82bb1d 100644
--- a/src/main.cpp
+++ b/src/main.cpp
@@ -1,3 +1,18 @@
+/**
+ * Copyright © 2017 IBM Corporation
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
#include <sdbusplus/bus.hpp>
#include "monitor.hpp"
diff --git a/src/monitor.cpp b/src/monitor.cpp
index 093b8e7..9e517fb 100644
--- a/src/monitor.cpp
+++ b/src/monitor.cpp
@@ -1,3 +1,18 @@
+/**
+ * Copyright © 2017 IBM Corporation
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
#include "monitor.hpp"
namespace phosphor
diff --git a/src/monitor.hpp b/src/monitor.hpp
index 5256582..63afebe 100644
--- a/src/monitor.hpp
+++ b/src/monitor.hpp
@@ -11,6 +11,12 @@
namespace monitoring
{
+/**
+ * @class Monitor
+ * @brief OpenBMC DBus Monitoring application
+ * @details A configurable application to perform a set of actions based on one
+ * or more conditions for items within a group
+ */
class Monitor
{
public:
@@ -21,15 +27,33 @@
Monitor& operator=(Monitor&&) = default;
~Monitor() = default;
+ /**
+ * @brief Constructs monitor object
+ *
+ * @param[in] bus - Dbus bus object
+ */
explicit Monitor(sdbusplus::bus::bus& bus);
+ /**
+ * @brief Process events triggered by the application starting
+ */
void processStart() noexcept;
+ /**
+ * @brief Handle an event being processed
+ *
+ * @param[in] msg - Dbus msg
+ * @param[in] event - Event to be handled
+ * @param[in] eventDef - The event's full definition
+ */
void handleEvent(sdbusplus::message::message& msg,
const Event& event,
const std::tuple<std::vector<std::shared_ptr<Event>>,
std::vector<Action>>& eventDef);
+ /**
+ * @brief An event's set of arguments
+ */
using eventArg = std::tuple<Monitor*,
const SignalEvent*,
const std::tuple<
@@ -37,16 +61,26 @@
std::vector<Action>>*>;
private:
+ /** @brief Connection for sdbusplus bus */
sdbusplus::bus::bus& bus;
-
+ /** @brief List of events to process */
static const std::vector<
std::tuple<std::vector<std::shared_ptr<Event>>,
std::vector<Action>>> events;
-
+ /** @brief List of event arguments */
std::vector<std::unique_ptr<eventArg>> eventArgs;
-
+ /** @brief list of Dbus matches for callbacks */
std::vector<sdbusplus::server::match::match> matches;
+ /**
+ * @brief Handle an event signal
+ *
+ * @param[in] msg - Data associated with the subscribed signal
+ * @param[in] data - Pointer to the event items's data
+ * @param[in] err - Contains any sdbus error reference if occurred
+ *
+ * @return 0
+ */
static int handleSignal(sd_bus_message* msg,
void* data,
sd_bus_error* err);