etl/docs/raw/patterns/Successor.txt

Successor

Adds successor traits to a derived class.
This template adds the ability for a class to store a successor to itself which allows the 'Chain of Responsibility' design pattern to be implemented in a consistent fashion. 

Note:
The successors do not have to be derived from etl::successor, but the member functions append_successor and clear_successor_chain cannot be used if they are not.

etl::successor<typename T>
T   The successor type
____________________________________________________________________________________________________
Member types

successor_type T
____________________________________________________________________________________________________
Constructors

successor()
Constructs a default successor.
has_successor() will return false.
____________________________________________________________________________________________________
successor(successor_type& s)
Constructs a successor from the supplied parameter s.
has_successor() will return true.
____________________________________________________________________________________________________
Member functions

void set_successor(successor_type& s)
Sets the successor to s.
Overwrites any previous successor.
has_successor() will return true.
____________________________________________________________________________________________________
template <typename... TSuccessors>
void set_successor(successor_type& s, TSuccessors&... rest)
Sets a series of successors to s.
Overwrites any previous successor.
20.28.0, C++11
____________________________________________________________________________________________________
template <typename TSuccessor>
void append_successor(TSuccessor& s)
Appends the successor to the end of the successor chain.
Only valid to call if all successors are derived from etl::successor.
20.28.0
____________________________________________________________________________________________________
template <typename TSuccessor, typename... TSuccessors>
void append_successor(TSuccessor& s, TSuccessors&... rest)
Appends the list of successors to the end of the successor chain.
Only valid to call if all successors are derived from etl::successor.
20.28.0, C++11
____________________________________________________________________________________________________
successor_type& get_successor() const
Gets a reference to the successor.
Undefined behaviour if a successor has not been set.
____________________________________________________________________________________________________
bool has_successor() const
Returns true if a successor has been set.
____________________________________________________________________________________________________
void clear_successor()
Clears the successor.
has_successor() will return false.
20.28.0
____________________________________________________________________________________________________
void clear_successor_chain()
Clears the successor for every successor in the chain starting from this successor.
Only valid to call if all successors are derived from etl::successor.
20.28.0
____________________________________________________________________________________________________
Error types

successor_exception Derived from etl::exception
successor_invalid   Derived from successor_exception 
____________________________________________________________________________________________________
Example

class IProcessor : public etl::successor<IProcessor>
{
  public:

  //*********************************
  virtual bool Check() = 0;

  //*********************************
  // Step though the successors until either the 
  // call is handled, or there are no successors left.
  bool Process()
  {
    bool handled = false;

    IProcessor* p = this;

    while (handled == false)
    {
      handled = p->Check();

      // Were we unable to handle call?
      if (handled == false)
      {
        // Do we have a successor?
        if (p->has_successor())
        {
          // Get the next successor.
          p = &(p->get_successor());
        }
        else
        {
          // We have reached the end of the chain.
          break;
        }
      }
    }

    return handled;
  }
};

//*********************************
class Processor1 : public IProcessor
{
  public:

  bool Check() override
  {
    return false;
  }
};

//*********************************
class Processor2 : public IProcessor
{
  public:

  bool Check() override
  {
    return false;
  }
};

//*********************************
class Processor3 : public IProcessor
{
  public:

  bool Check() override
  {
    return false;
  }
};

//*********************************
class Processor4 : public IProcessor
{
public:

  bool Check() override
  {
    return true;
  }
};

Processor1 processor1a;
Processor1 processor1b;
Processor2 processor2a;
Processor2 processor2b;
Processor3 processor3;
Processor4 processor4;

processor1a.append_successor(processor2a, processor3);
processor1b.append_successor(processor2b, processor4);

bool b1a = processor1a.Process(); // Returns false, nothing handles the process call.
bool b1b = processor1b.Process(); // Returns true, processor4 handles the process call.