Implement Stdin Event Handler (#45)

* Implement Stdin Event Handler

Signed-off-by: jparisu <javierparis@eprosima.com>

* Add code documentation

Signed-off-by: jparisu <javierparis@eprosima.com>

* apply suggestions

Signed-off-by: jparisu <javierparis@eprosima.com>

* uncrustify

Signed-off-by: jparisu <javierparis@eprosima.com>

---------

Signed-off-by: jparisu <javierparis@eprosima.com>

Author: jparisu

cpp_utils/include/cpp_utils/event/StdinEventHandler.hpp

@@ -0,0 +1,138 @@
+// Copyright 2023 Proyectos y Sistemas de Mantenimiento SL (eProsima).
+//
+// 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.
+
+#pragma once
+
+#include <atomic>
+#include <functional>
+#include <thread>
+
+#include <cpp_utils/event/EventHandler.hpp>
+#include <cpp_utils/library/library_dll.h>
+#include <cpp_utils/time/time_utils.hpp>
+#include <cpp_utils/wait/CounterWaitHandler.hpp>
+
+namespace eprosima {
+namespace utils {
+namespace event {
+
+/**
+ * This object allows to read from a \c istream , commonly from \c std::cin .
+ * Every time there is a message written in std::cin AND this object is enabled to read it, the string input
+ * is given in callback call.
+ *
+ * @warning This EventHandler is different than others in the way that it is obligated to give the number of inputs
+ * that it must read (and not read until stop). This is because there is no easy way to stop a thread that
+ * is waiting in std::cin in a multi-platform way.
+ * This also implies that once the handler is waiting for stdin input, there is no way to stop it.
+ */
+class StdinEventHandler : public EventHandler<std::string>
+{
+public:
+
+    /**
+     * @brief Construct a new Stdin Event Handler with specific callback
+     *
+     * @param callback : callback to call when there is new data in stdin
+     * @param read_lines : whether to read whole lines or read separated in spaces
+     * @param lines_to_read : number of lines that this EventHandler must expect. Could be incremented by
+     *  \c read_one_more_line .
+     * @param source : source \c istream to get data from.
+     *
+     * @note \c source is very useful for testing purpose.
+     * However, it does not make much sense in any other scenario, and it is dangerous to use something different
+     * than std::cin, as the object stores a reference, and this referenced istream must survive this object.
+     */
+    CPP_UTILS_DllAPI
+    StdinEventHandler(
+            std::function<void(std::string)> callback,
+            const bool read_lines = true,
+            const int lines_to_read = 0,
+            std::istream& source = std::cin);
+
+    /**
+     * @brief Destroy the StdinEventHandler object
+     *
+     * Calls \c unset_callback
+     */
+    CPP_UTILS_DllAPI
+    ~StdinEventHandler();
+
+    /**
+     * @brief In order to read more than the lines given by ctor argument, use this method to increase value by 1.
+     *
+     * There is no easy way to stop a thread reading in a istream.
+     * Thus the handler must know how much times it should read.
+     * This method increase in 1 the number of times to read.
+     *
+     * The standard use of this class is to call this method each time a stdin input is expected.
+     */
+    CPP_UTILS_DllAPI
+    void read_one_more_line();
+
+protected:
+
+    /**
+     * @brief Internal thread to read from \c source_ .
+     *
+     * This thread waits first to this object to give it permission to start waiting for data in \c source_ by
+     * waiter \c activation_times_ .
+     * Every time allowed, it waits for 1 new input and give it by calling callback.
+     *
+     * @warning callback is called from this method, so until the
+     * callback does not finish, the object cannot start reading again.
+     */
+    CPP_UTILS_DllAPI
+    void stdin_listener_thread_routine_() noexcept;
+
+    /**
+     * @brief Override \c callback_set_ from \c EventHandler .
+     *
+     * It starts reading thread.
+     *
+     * It is already guarded by \c event_mutex_ .
+     */
+    virtual void callback_set_nts_() noexcept override;
+
+    /**
+     * @brief Override \c callback_set_ from \c EventHandler .
+     *
+     * It stops reading thread.
+     *
+     * It is already guarded by \c event_mutex_ .
+     */
+    virtual void callback_unset_nts_() noexcept override;
+
+    //! Reading thread
+    std::thread stdin_listener_thread_;
+
+    //! Counter that contains the number of times the thread is allowed to start waiting for data from source_.
+    CounterWaitHandler activation_times_;
+
+    /**
+     * @brief istream source from where to read.
+     *
+     * This is very useful for testing.
+     * However it is dangerous to have a reference here to an external object.
+     * Commonly this will be std::cin that does not die till the end of process.
+     */
+    std::istream& source_;
+
+    //! Whether to read whole lines or stop reading in a space.
+    const bool read_lines_;
+};
+
+} /* namespace event */
+} /* namespace utils */
+} /* namespace eprosima */

cpp_utils/include/cpp_utils/utils.hpp

@@ -63,7 +63,8 @@ FileAccessMode operator &(
         FileAccessMode mode_b);
 
 //! Perform the wildcard matching using file comparison method
-CPP_UTILS_DllAPI bool match_pattern(
+CPP_UTILS_DllAPI
+bool match_pattern(
         const std::string& pattern,
         const std::string& str) noexcept;
 
@@ -74,7 +75,8 @@ CPP_UTILS_DllAPI bool match_pattern(
  *
  * @param [in,out] st : string to modify
  */
-CPP_UTILS_DllAPI void to_lowercase(
+CPP_UTILS_DllAPI
+void to_lowercase(
         std::string& st) noexcept;
 
 /**
@@ -135,7 +137,8 @@ bool are_set_of_ptr_equal(
  *
  * @param formatter msg of the unexpected case.
  */
-CPP_UTILS_DllAPI void tsnh(
+CPP_UTILS_DllAPI
+void tsnh(
         const Formatter& formatter);
 
 /**
@@ -165,7 +168,8 @@ std::set<std::shared_ptr<Parent>> convert_set_to_shared(
  * @return true if file is accessible regarding the permissions given
  * @return false otherwise
  */
-CPP_UTILS_DllAPI bool is_file_accessible(
+CPP_UTILS_DllAPI
+bool is_file_accessible(
         const char* file_path,
         FileAccessMode access_mode = FileAccessMode::exist) noexcept;
 
@@ -179,20 +183,24 @@ CPP_UTILS_DllAPI bool is_file_accessible(
  * @return to string convertion of the element
  */
 template <typename T>
-CPP_UTILS_DllAPI std::string generic_to_string(
+CPP_UTILS_DllAPI
+std::string generic_to_string(
         const T& element);
 
 template <typename T>
-CPP_UTILS_DllAPI void* copy_to_void_ptr(
+CPP_UTILS_DllAPI
+void* copy_to_void_ptr(
         const T* source,
         size_t size = sizeof(T));
 
-CPP_UTILS_DllAPI bool replace_first(
+CPP_UTILS_DllAPI
+bool replace_first(
         std::string& st,
         std::string const& to_replace,
         std::string const& replace_by);
 
-CPP_UTILS_DllAPI unsigned int replace_all(
+CPP_UTILS_DllAPI
+unsigned int replace_all(
         std::string& st,
         std::string const& to_replace,
         std::string const& replace_by);
@@ -209,16 +217,61 @@ CPP_UTILS_DllAPI unsigned int replace_all(
  *
  * @return number of strings removed.
  */
-CPP_UTILS_DllAPI unsigned int strip_str(
+CPP_UTILS_DllAPI
+unsigned int strip_str(
         std::string& to_strip,
         const std::string& replace_by = "",
         const std::set<std::string>& undesired_strings = {"\n", "\r"});
 
-CPP_UTILS_DllAPI std::string number_trailing_zeros_format(
+CPP_UTILS_DllAPI
+std::string number_trailing_zeros_format(
         int value_to_print,
         unsigned int n_chars,
         bool allow_more_chars = true);
 
+/**
+ * @brief Split string \c source by every delimiter in \c delimiters .
+ *
+ * This method uses split_string(const std::vector<std::string>&, const std::string&) .
+ * For more information, please check that documentation.
+ */
+CPP_UTILS_DllAPI
+std::vector<std::string> split_string(
+        const std::string& source,
+        const std::set<std::string>& delimiters);
+
+/**
+ * @brief Split each string in \c source by \c delimiter .
+ *
+ * This method uses split_string(const std::string&, const std::string&) .
+ * For more information, please check that documentation.
+ */
+CPP_UTILS_DllAPI
+std::vector<std::string> split_string(
+        const std::vector<std::string>& source,
+        const std::string& delimiter);
+
+/**
+ * @brief Split a string \c source by \c delimiter .
+ *
+ * The delimiter will no longer exist in any of the result strings.
+ *
+ * @example source:"Some String" delimiter:" " result:["Some", "String"]
+ * @example source:" " delimiter:" " result:["", ""]
+ *
+ * @param source string to divide in tokens
+ * @param delimiter string to look for in source and divide it with
+ *
+ * @return vector with strings
+ *
+ * @warning Some results could be empty strings if the delimiter is at the start, end or repeated along source.
+ *
+ * @post There will be always at least 1 element in the result vector
+ */
+CPP_UTILS_DllAPI
+std::vector<std::string> split_string(
+        const std::string& source,
+        const std::string& delimiter);
 
 } /* namespace utils */
 } /* namespace eprosima */

cpp_utils/src/cpp/event/StdinEventHandler.cpp

@@ -0,0 +1,81 @@
+// Copyright 2023 Proyectos y Sistemas de Mantenimiento SL (eProsima).
+//
+// 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 <cpp_utils/Log.hpp>
+#include <cpp_utils/event/StdinEventHandler.hpp>
+#include <cpp_utils/exception/InitializationException.hpp>
+
+namespace eprosima {
+namespace utils {
+namespace event {
+
+StdinEventHandler::StdinEventHandler(
+        std::function<void(std::string)> callback,
+        const bool read_lines /* = true */,
+        const int lines_to_read /* = 0 */,
+        std::istream& source /* = std::cin */)
+    : activation_times_(0, lines_to_read, false)
+    , source_(source)
+    , read_lines_(read_lines)
+{
+    set_callback(callback);
+}
+
+StdinEventHandler::~StdinEventHandler()
+{
+    unset_callback();
+}
+
+void StdinEventHandler::read_one_more_line()
+{
+    ++activation_times_;
+}
+
+void StdinEventHandler::stdin_listener_thread_routine_() noexcept
+{
+    auto awake_reason = activation_times_.wait_and_decrement();
+    while (awake_reason == AwakeReason::condition_met)
+    {
+        std::string read_str;
+
+        // Read lines or separated by spaces
+        if (read_lines_)
+        {
+            getline(source_, read_str);
+        }
+        else
+        {
+            source_ >> read_str;
+        }
+        event_occurred_(read_str);
+
+        awake_reason = activation_times_.wait_and_decrement();
+    }
+}
+
+void StdinEventHandler::callback_set_nts_() noexcept
+{
+    activation_times_.enable();
+    stdin_listener_thread_ = std::thread(&StdinEventHandler::stdin_listener_thread_routine_, this);
+}
+
+void StdinEventHandler::callback_unset_nts_() noexcept
+{
+    activation_times_.disable();
+    stdin_listener_thread_.join();
+}
+
+} /* namespace event */
+} /* namespace utils */
+} /* namespace eprosima */