hoo2/tbx
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

WIP: sequencer rework

Browse Source
This commit is contained in:
hoo2
2021-09-26 22:30:36 +03:00
parent fd64d8726c
commit ca38dfa2f1
4 changed files with 694 additions and 372 deletions
Download Patch File Download Diff File Expand all files Collapse all files
include/utils/sequencer.h
+250 -182
View File
@@ -39,7 +39,6 @@
#include <ctime>
#include <array>
#include <string_view>
#include <limits>
#include <type_traits>
#include <utility>
#include <tuple>
@@ -51,21 +50,36 @@ namespace tbx {
* \brief
* A CRTP base class to provide the sequencer functionality.
*
* Sequencer can automate communication with a terminal-like device such as AT-command modems etc...
* Sequencer is a script engine with receive/transmit functionalities based on predicates. It has:
* - A program counter like variable named \c step.
* - \c step actions like NEXT, GOTO exit with status etc...
* - Input data match predicates to trigger those actions.
* - Input data handlers to trigger external functionality on predicate match
* - Output data handlers to "edit" data before transmiting them
* - A small predicate set provided to the user. (starts_with, ends_with, contains).
*
* Sequencer can automate communication with a terminal-like device such as AT-command modems, can
* be used to implement communication protocols, or even small http servers.
*
* It can operate based on a script array and handle the outgoing commands and incoming responses.
* The user can create matching rules on received data and hook handlers and actions on them.
*
* The derived class (implementation) has to provide:
* 1) size_t get(Data_t* data);
* This function return 0 or a number of Data_t items. The data points to buffer for the input data.
*
* 3) size_t contents_ (Data_t* data);
* This function return 0 or a number of Data_t items without removing them from the implementer's container
* The data points to buffer for the input data.
*
* 2) size_t put(const Data_t* data, size_t n);
* This function sends to implementation the data pointed by \c data witch have size \c n.
* 3) clock_t clock();
*
* 4) clock_t clock();
* This function return a number to be used as time. The units of this function may be arbitrary but they
* match the units in \c record_t::timeout field.
*
* \tparam Impl_t The type of derived class
* \tparam Cont_t The container type holding the data of type \c Data_t for the derived class.
* \tparam Data_t The char-like stream item type. Usually \c char
* \tparam N The size of the sequence buffer to temporary store each line from get().
*
@@ -73,23 +87,27 @@ namespace tbx {
* We need access to derived class container to sneaky get a range of the data beside
* the normal data flow, in order to implement the \see control_t::DETECT operation.
*/
template <typename Impl_t, typename Cont_t, typename Data_t, size_t N>
template <typename Impl_t, typename Data_t, size_t N>
class sequencer {
_CRTP_IMPL(Impl_t);
static_assert(
std::is_same_v<typename Cont_t::value_type, Data_t>,
"Cont_t must be a container of type Data_t"
);
// local type dispatch
using range_t = typename Cont_t::range_t;
//! \name Public types
//! @{
public:
using value_type = Data_t;
using pointer_type = Data_t*;
using size_type = size_t;
using string_view = std::basic_string_view<Data_t>;
/*!
* The sequencer engine status. A variable of this type is returned by
* \see action_().
*/
enum class seq_status_t {
CONTINUE, //!< Means we keep looping
EXIT //!< Means, we exit with status the one indicated by \c action_t of the \c record_t
};
using str_view_t = std::basic_string_view<Data_t>;
//! \enum control_t
//! \brief The control type of the script entry.
enum class control_t {
@@ -107,28 +125,50 @@ class sequencer {
//! is buffered with a delimiter and we seek for data that don't follow the delimiter pattern.
//!
//! For example:
//! A modem sends reponses with '\n' termination but for some "special" command it opens a cursor
//! A modem sends responses with '\n' termination but for some "special" command it opens a cursor
//! lets say ">$ " without '\n' at the end.
};
//! \enum action_t
//! \brief Possible response actions for the sequencer
//! \brief
//! Possible response actions for the sequencer. This is the
//! equivalent of changing the program counter of the sequencer
//! and is composed by a type and a value.
//!
struct action_t {
enum {
NO =0, NEXT, GOTO, EXIT_OK, EXIT_ERROR
NO =0, //!< Do not change sequencer's step
NEXT, //!< Go to next sequencer step. In case of EXPECT/DETECT block of records
//!< skip the entire block of EXPECT[, OR_EXPECT[, OR_EXPECT ...]] and go
//!< to the next (non OR_*) control record.
GOTO, //!< Manually sets the step counter to the number of the \c step member.
EXIT, //!< Instruct for an exit returning the action.value as status
} type;
size_t step;
size_t value; //!< Used by \c GOTO to indicate the next sequencer's step.
};
//! \enum match_t
//! \brief Token match types
enum class match_t {
NO, STARTS_WITH, ENDS_WITH, CONTAINS, nSTARTS_WITH, nENDS_WITH, nCONTAINS
};
static constexpr action_t no_action = {action_t::NO, 0};
static constexpr action_t next = {action_t::NEXT, 0};
template <size_t GOTO>
static constexpr action_t go_to = {action_t::GOTO, static_cast<size_t>(GOTO)};
static constexpr action_t exit_ok = {action_t::EXIT, 0};
static constexpr action_t exit_error = {action_t::EXIT, static_cast<size_t>(-1)};
template <size_t Status>
static constexpr action_t exit = {action_t::EXIT, static_cast<size_t>(Status)};
/*!
* Match handler function pointer type.
* Expects a pointer to buffer and a size and returns status
* Match binary predicate function pointer type.
* Expects two string views and return a boolean.
* It is used by EXPECT/DETECT blocks to trigger their {handler, action} pair.
*/
using match_ft = bool (*) (const string_view haystack, const string_view needle);
/*!
* Send/Receive handler function pointer type.
* Expects a pointer to buffer and a size and returns status.
* It is used on predicate match on EXPECT/DETECT blocks, or as data wrapper on SEND blocks.
*/
using handler_ft = void (*) (const Data_t*, size_t);
@@ -136,16 +176,18 @@ class sequencer {
* \struct record_t
* \brief
* Describes the sequencer's script record entry (line).
*
* Each line consist from a control, 2 blocks and a timeout. The control says if we send or receive data.
* The blocks contain the data and the matching information. And the timeout guards the entire line.
*/
struct record_t {
control_t control; //!< The type of the entry
str_view_t token;
match_t match;
handler_ft handler; //!< The handler to called if the match is successful.
action_t action;
control_t control; //!< The control type of the entry
string_view token; //!< String view to token data. [MUST BE null terminated].
//!< This is passed as 2nd argument to match predicate on EXPECT/DETECT, or as
//! {data, size} pair to SEND handler and put_().
//!< If unused set it to ""
match_ft match; //!< Match predicate to used in EXPECT/DETECT blocks
//!< If unused set it to nullptr
handler_ft handler; //!< The handler to called if the match is successful, or before put_()
//!< If unused set it to nullptr
action_t action; //!< Indicates the step manipulation if the match is successful or after NOP and put_()
clock_t timeout; //!< Timeout in CPU time
};
@@ -156,35 +198,95 @@ class sequencer {
*
* The user can create arrays as the example bellow to act as a script.
* \code
* const std::array<Seq::record_t, 8> script = {{
* / * 0 * / {Seq::control_t::NOP, {"", Seq::match_t::NO, nullptr, Seq::action_t::GOTO, 1}, 1000}, //delay 1000 clocks
* / * 1 * / {Seq::control_t::SEND, {"ATE0\r\n", Seq::match_t::NO, nullptr, Seq::action_t::NEXT, 0}, 1000},
* / * 2 * / {Seq::control_t::EXPECT, {{
* {"OK\r\n", Seq::match_t::ENDS_WITH, nullptr, Seq::action_t::NEXT, 0},
* {"ERROR", Seq::match_t::CONTAINS, nullptr, Seq::action_t::EXIT_ERROR, 0} }},
* 1000
* },
* // ...
* }};
* Seq s;
* const Seq::script_t<4> script = {{
* {Seq::control_t::NOP, "", Seq::nil, Seq::nil, {Seq::action_t::GOTO, 1}, 1000},
*
* {Seq::control_t::SEND, "ATE0\r\n", Seq::nil, Seq::nil, {Seq::action_t::NEXT, 0}, 0},
* {Seq::control_t::EXPECT, "OK\r\n", Seq::ends_with, Seq::nil, {Seq::action_t::EXIT_OK, 0}, 1000},
* {Seq::control_t::OR_EXPECT, "ERROR", Seq::contains, Seq::nil, {Seq::action_t::EXIT_ERROR, 0}, 0}
* }};
* s.run(script);
* \endcode
*/
template <size_t Nrecords>
using script_t = std::array<record_t, Nrecords>;
enum class seq_status_t {
CONTINUE, EXIT_OK, EXIT_ERROR
/*!
* \brief
* Check if the \c stream1 is equal to \c stream2
* \param stream1 The stream in witch we search [The input buffer]
* \param stream2 What we search [The record's token]
* \return True on success, false otherwise
*/
static constexpr auto equals = [](const string_view stream1, const string_view stream2) -> bool {
return (stream1 == stream2);
};
/*!
* \brief
* Check if the \c stream starts with the \c prefix
* \param stream The stream in witch we search [The input buffer]
* \param prefix What we search [The record's token]
* \return True on success, false otherwise
*/
static constexpr auto starts_with = [](const string_view stream, const string_view prefix) -> bool {
return (stream.rfind(prefix, 0) != string_view::npos);
};
/*!
* \brief
* Check if the \c stream ends with the \c postfix
* \param stream The stream in witch we search [The input buffer]
* \param postfix What we search [The record's token]
* \return True on success, false otherwise
*/
static constexpr auto ends_with = [](const string_view stream, const string_view postfix) -> bool {
if (stream.size() < postfix.size())
return false;
return (
stream.compare(
stream.size() - postfix.size(),
postfix.size(),
postfix) == 0
);
};
/*!
* \brief
* Check if the \c haystack contains the \c needle
* \param haystack The stream in witch we search [The input buffer]
* \param needle What we search [The record's token]
* \return True on success, false otherwise
*/
static constexpr auto contains = [](const string_view haystack, const string_view needle) -> bool {
return (haystack.find(needle) != string_view::npos);
};
//! Always false predicate
static constexpr auto always_true = [](const string_view s1, const string_view s2) -> bool {
(void)s1; (void)s2;
return true;
};
//! Always false predicate
static constexpr auto always_false = [](const string_view s1, const string_view s2) -> bool {
(void)s1; (void)s2;
return false;
};
//! Empty predicate or handler
static constexpr auto nil = nullptr;
//! @}
//! \name Constructor / Destructor
//! \name Object lifetime
//!@{
protected:
~sequencer () = default; //!< \brief Allow destructor from derived only
sequencer () = default; //!< \brief A default constructor from derived only
~sequencer () = default; //!< \brief Allow destructor from derived only
constexpr sequencer () noexcept = default; //!< \brief A default constructor from derived only
sequencer(const sequencer&) = delete; //!< No copies
sequencer& operator= (const sequencer&) = delete; //!< No copy assignments
//!@}
@@ -193,60 +295,23 @@ class sequencer {
//! @{
private:
size_t get_ (Data_t* data) { return impl().get (data); }
size_t contents_ (Data_t* data) { return impl().contents(data); }
size_t put_ (const Data_t* data, size_t n) { return impl().put (data, n); }
const range_t contents_ () const { return impl().contents(); }
clock_t clock_ () { return impl().clock(); }
//! @}
//! \name Private functionality
//! @{
private:
/*!
* \brief
* Check if the \c stream starts with the \c prefix
* \param stream The stream in witch we search
* \param prefix What we search
* \return True on success, false otherwise
*/
static bool starts_with_ (const str_view_t stream, const str_view_t prefix) {
return (stream.rfind(prefix, 0) != str_view_t::npos);
}
/*!
* \brief
* Check if the \c stream ends with the \c postfix
* \param stream The stream in witch we search
* \param postfix What we search
* \return True on success, false otherwise
* Check if there is a handler and call it
* \param handler The handler to check
* \param buffer String view to buffer to pass to handler
* \return True if handler is called
*/
static bool ends_with_ (const str_view_t stream, const str_view_t postfix) {
if (stream.size() < postfix.size())
return false;
return (
stream.compare(
stream.size() - postfix.size(),
postfix.size(),
postfix) == 0
);
}
/*!
* \brief
* Check if the \c haystack contains the \c needle
* \param haystack The stream in witch we search
* \param needle What we search
* \return True on success, false otherwise
*/
static bool contains_ (const str_view_t haystack, const str_view_t needle) {
return (haystack.find(needle) != str_view_t::npos);
}
bool is_step_extend (control_t control) {
return (control == control_t::OR_EXPECT || control == control_t::OR_DETECT);
}
static bool handle_ (handler_ft handler, const str_view_t buffer = str_view_t{}) {
if (handler) {
constexpr bool handle_ (handler_ft handler, const string_view buffer = string_view{}) {
if (handler != nullptr) {
handler (buffer.begin(), buffer.size());
return true;
}
@@ -255,25 +320,36 @@ class sequencer {
/*!
* \brief
* Return the new sequencer's step value.
* Return the new sequencer's step value and the sequencer's loop status as pair.
*
* Step is index to the sequencer's script array.
*
* \param current_idx The current step value
* \param action The advancing type
* \param go_idx The new value of the step in the case of GOTO type
* \return The new sequencer's step value
* \param script Reference to entire script.
* \param step The current step
* \return new step - status pair
*/
static std::pair<size_t, seq_status_t> action_ (const action_t& action, size_t step) {
switch (action.type) {
template <size_t Steps>
constexpr std::pair<size_t, seq_status_t> action_ (const script_t<Steps>& script, size_t step) {
control_t skip_while{};
size_t s;
switch (script[step].action.type) {
default:
case action_t::NO: return std::make_pair(step, seq_status_t::CONTINUE);
case action_t::NEXT: return std::make_pair(++step, seq_status_t::CONTINUE);
case action_t::GOTO: return std::make_pair(action.step, seq_status_t::CONTINUE);
case action_t::EXIT_OK:
return std::make_pair(std::numeric_limits<size_t>::max(), seq_status_t::EXIT_OK);
case action_t::EXIT_ERROR:
return std::make_pair(std::numeric_limits<size_t>::max(), seq_status_t::EXIT_ERROR);
case action_t::NO: return std::make_pair(step, seq_status_t::CONTINUE);
case action_t::NEXT:
switch (script[step].control) {
case control_t::NOP: return std::make_pair(++step, seq_status_t::CONTINUE);
case control_t::SEND: return std::make_pair(++step, seq_status_t::CONTINUE);
case control_t::EXPECT:
case control_t::OR_EXPECT: skip_while = control_t::OR_EXPECT; break;
case control_t::DETECT:
case control_t::OR_DETECT: skip_while = control_t::OR_DETECT; break;
}
s = step;
while (script[++s].control == skip_while)
;
return std::make_pair(s, seq_status_t::CONTINUE);
case action_t::GOTO: return std::make_pair(script[step].action.value, seq_status_t::CONTINUE);
case action_t::EXIT: return std::make_pair(script[step].action.value, seq_status_t::EXIT);
}
}
@@ -281,42 +357,25 @@ class sequencer {
public:
/*!
* \brief
* Checks if the \c needle matches the \c haystack.
*
* \param type The type of matching functionality
* \param haystack The stream in witch we search
* \param needle The stream we search
* \return True on match
*/
static bool match (const str_view_t haystack, const str_view_t needle, match_t type) {
switch (type) {
default:
case match_t::NO: return true;
case match_t::STARTS_WITH: return starts_with_(haystack, needle);
case match_t::ENDS_WITH: return ends_with_(haystack, needle);
case match_t::CONTAINS: return contains_(haystack, needle);
case match_t::nSTARTS_WITH: return !starts_with_(haystack, needle);
case match_t::nENDS_WITH: return !ends_with_(haystack, needle);
case match_t::nCONTAINS: return !contains_(haystack, needle);
}
}
//! \return The buffer size of the sequencer
constexpr size_t size() const { return N; }
/*!
* \brief
* A static functionality to provide access to sequencer's inner matching mechanism.
* Checks the \c buffer against \c handle and calls its action if needed.
*
* \param handle Reference to handle
* \param buffer The buffer to check
* \param buffer The buffer to check (1st parameter to match)
* \param token String view to check against buffer (2nd parameter to match)
* \param handler Function pointer to match predicate to use
* \param handle Reference to handle to call on match
*
* \return True on match, false otherwise
*/
static bool check_handle (const str_view_t token, match_t match_type, handler_ft handle, const str_view_t buffer) {
if (match(buffer, token, match_type)) {
handle_ (handle, buffer);
return true;
}
constexpr bool check_handle (const string_view buffer, const string_view token, match_ft match, handler_ft handle) {
if (match != nullptr && match(buffer, token))
return handle_ (handle, buffer);
return false;
}
@@ -325,92 +384,101 @@ class sequencer {
* Run the script array
*
* The main sequencer functionality. It starts with the first entry of the array.
* - If the entry is \c NOP it executes the action after the timeout.
* \c token and \c handler are discarded.
* - If the entry is \c SEND it uses the first handle block's token to send and executes the action after that.
* \c timeout is discarded.
* - If the entry is \c EXCEPTS it continuously try to receive data using implementation's get until one
* of the handle blocks match.
* On match:
* - Calls the handler if there is one
* - Executes the action
* - Skips the next handle blocks if there is any.
* If there is no match on timeout it return status_t::EXIT_ERROR
* - If the entry is \c DETECT it continuously try to detect data using implementation's contents until one
* of the handle blocks match.
* On match:
* - Calls the handler if there is one
* - Executes the action
* - Skips the next handle blocks if there is any.
* If there is no match on timeout it return status_t::EXIT_ERROR
*
* \tparam Steps The number of steps of the script
* \tparam Nhandles The number of handle blocks in the each script record.
* - If the record is \c NOP it executes the action after the timeout.
* \c NOP uses {\c action_t, \c timeout}.
* - If the record is \c SEND passes the token to handler (if any), then to put_() and executes the action after that.
* \c SEND uses {\c token, \c handler, \c action_t}
* - If the record is \c EXCEPT it continuously try to receive data using \see get_()
* * If no data until timeout, exit with failure
* * On data reception for this record AND for each OR_EXPECT that follows, calls the match predicate
* by passing the received data and token.
* On predicate match
* - Calls the handler if there is one
* - Executes the action. No farther EXPECT, OR_EXPECT, ... checks are made.
* - If the record is \c DETECT it continuously try to receive data using \see contents_()
* * If no data until timeout, exit with failure
* * On data reception for this record AND for each OR_DETECT that follows, calls the match predicate
* by passing the received data and token.
* On predicate match
* - Calls the handler if there is one
* - Executes the action. No farther DETECT, OR_DETECT, ... checks are made.
*
* \tparam Steps The number of records of the script
*
* \param script Reference to script to run
* \return The status of entire operation as described above
* \arg 0 Success
* \arg (size_t)-1 Failure
* \arg other Arbitrary return status
*/
template <size_t Steps>
bool run (const script_t<Steps>& script) {
size_t run (const script_t<Steps>& script) {
Data_t buffer[N];
size_t resp_size;
seq_status_t status{seq_status_t::CONTINUE};
size_t step =0, p_step =0;
clock_t mark = clock_();
do {
if (step != p_step) {
seq_status_t status{seq_status_t::CONTINUE}; do {
const record_t& record = script[step]; // get reference ot current line
if (step != p_step) { // renew time marker in each step
p_step = step;
mark = clock_();
}
switch (script[step].control) {
switch (record.control) {
default:
case control_t::NOP:
if ((clock_() - mark) >= script[step].timeout)
std::tie(step, status) = action_ (script[step].action, step);
if ((clock_() - mark) >= record.timeout)
std::tie(step, status) = action_ (script, step);
break;
case control_t::SEND:
if (put_(script[step].token.data(), script[step].token.size()) != script[step].token.size())
return false;
std::tie(step, status) = action_ (script[step].action, step);
if (record.handler != nullptr)
record.handler(record.token.data(), record.token.size());
if (put_(record.token.data(), record.token.size()) != record.token.size())
return exit_error.value;
std::tie(step, status) = action_ (script, step);
break;
case control_t::EXPECT:
case control_t::OR_EXPECT:
resp_size = get_(buffer);
if (resp_size) {
for (size_t s = step ; script[s].control == control_t::OR_EXPECT; ++s) {
if (match({buffer, resp_size}, script[s].token, script[s].match)) {
size_t s = step ; do{
if (script[s].match != nullptr && script[s].match({buffer, resp_size}, script[s].token)) {
handle_ (script[s].handler, {buffer, resp_size});
std::tie(step, status) = action_ (script[s].action, s);
std::tie(step, status) = action_ (script, s);
break;
}
}
} while (script[++s].control == control_t::OR_EXPECT);
}
if (script[step].timeout && (clock_() - mark) >= script[step].timeout)
return false;
if (record.timeout && (clock_() - mark) >= record.timeout)
return exit_error.value;
break;
case control_t::DETECT:
case control_t::OR_DETECT:
auto data = contents_();
if (data.begin() != data.end()) {
for (size_t s = step ; script[s].control == control_t::OR_DETECT ; ++s) {
if (match({buffer, resp_size}, script[s].token, script[s].match)) {
resp_size = contents_(buffer);
if (resp_size) {
size_t s = step ; do {
if (script[s].match != nullptr && script[s].match({buffer, resp_size}, script[s].token)) {
handle_ (script[s].handler, {buffer, resp_size});
std::tie(step, status) = action_ (script[s].action, s);
std::tie(step, status) = action_ (script, s);
break;
}
}
} while (script[++s].control == control_t::OR_DETECT);
}
if (script[step].timeout && (clock_() - mark) >= script[step].timeout)
return false;
if (record.timeout && (clock_() - mark) >= record.timeout)
return exit_error.value;
break;
} // switch (it.control)
} // switch (record.control)
} while ( status == seq_status_t::CONTINUE);
return (status == seq_status_t::EXIT_OK);
return step; // step here is set by action_ as the return status
}
};