src/vpp-api/vom/om.hpp

/*
 * Copyright (c) 2017 Cisco and/or its affiliates.
 * 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.
 */

#ifndef __VOM_OM_H__
#define __VOM_OM_H__

#include <algorithm>
#include <memory>
#include <set>

#include "vom/client_db.hpp"
#include "vom/hw.hpp"

/**

The VPP Object Model (VOM) library.

Before we begin, a glossary of terms:
   - Agent or client: A user mode process that links to and uses the VOM library
     to programme VPP
   - VPP: A running instance of VPP
   - High Availability (HA): Scenarios where the client and/or VPP restart with
     minimal service interruption.
   - CReate, Update, Delete (CRUD): An API style where the producer issues
     notifications to changes to objects

The VOM is a C++ library that models entities in VPP as C++ classes. The
 relationships between VOM objects and VPP entities is not always 1:1. Some
 effort has been made to construct a higher level, more abstract API to VPP
 programming*.
The client programming model is simple (or at least I intended it to be..). The
client deals in ‘desired’ state, that is, it expresses the objects it wants to
exists (in VPP) and the properties that the object should have, i.e**;
    Interface af1(“my-af-packet-1”, AFPACKET, admin::UP);
Then the client ‘writes’ this object into the ‘model’
    OM::write(“clients-thing-1”, af1);

“clients-thing-1” is a description of the entity within the client’s domain that
‘owns’ (or has locked or has a reference to) the VOM object. There can be many
owners of each VOM object. It will be the last owner’s update that will be
programmed in VPP. This model means that the client is not burdened with
maintaining which of its objects have created which VOM objects. If the client
is itself driven by a CRUD API, then create notifications are implemented as
 above. Update notifications add two extra statements;
    OM::mark(“clients-thing-1”);
    … do writes ….
    OM::sweep(“clients-thing-1”);
These ‘mark’ and ‘sweep’ statements are indications to OM that firstly, indicate
that all the objects owned by “clients-thing-1” are now stale, i.e that the
client may no longer need them. If one of the subsequent writes should update a
stale object, then it is no longer stale. The sweep statement will ‘remove’ all
the remaining stale objects. In this model, the client does not need to maintain
the mapping of VOM objects to its own objects – it can simply express what it
needs now.
The delete notification is simply:
     OM::remove(“clients-thing-1”);
Which will remove all the objects in VOM that are owned by “clients-thing-1”.
Where ‘remove’ in this sense means unlock and unreference, the VOM object, and
VPP state, will only be truly removed once there are no more owners. This is
equivalent to a mark & sweep with no intermediate writes.

To provide this client side model the VOM is a stateful library, meaning that
for each entity it creates in VPP, VOM maintains its own representation of that
object. VOM can therefore be memory hungry. The desired state is expressed by
the client, the ‘actual’ state is maintained by VOM. VOM will consolidate the
two states when the client writes to the OM and thus issue VPP only the changes
required.

The concepts of ownership and statefulness also allow the support for HA
scenarios.
VPP restart: When VPP restarts, VOM will reconnect and ‘replay’ its state, in
dependency order, to VPP. The client does not need to regenerate its desired
state.
Client restart: when the client restarts, VOM will read/dump the current state
of all VPP objects and store them in the OM owned by the special owner “boot”.
As the client reprogrammes its desired state, objects will become owned by both
the boot process and the client. At the point in time, as determined by the
client, all stale state, that owned only by boot, can be purged. Hence the
system reaches the correct final state, with no interruption to VPP forwarding.


Basic Design:

Each object in VOM (i.e. an interface, route, bridge-domain, etc) is stored in a
per-type object database, with an object-type specific key. This ‘singular’ DB
has a value-type of a weak pointer to the object. I use the term ‘singular’ to
refer to the instance of the object stored in these databases, to be distinct
from the instances the client constructs to represent desired state.
The ‘client’ DB maintains the mapping of owner to object. The value type of the
client DB is a shared pointer to the singular instance of the owned object.
Once all the owners are gone, and all the shared pointers are destroyed, the
singular instance is also destroyed.

Each VOM object has some basic behaviour:
  update: issue to VPP an update to this object’s state. This could include the
          create
  sweep: delete the VPP entity – called when the object is destroyed.
  replay: issue to VPP all the commands needed to re-programme (VPP restart HA
          scenario)
  populate: read state from VPP and add it to the OM (client restart HA
scenario)

The object code is boiler-plate, in some cases (like the ACLs) even template.
The objects are purposefully left as simple, functionality free as possible.

Communication with VPP is through a ‘queue’ of ‘commands’. A command is
essentially an object wrapper around a VPP binary API call (although we do use
the VAPI C++ bindings too). Commands come in three flavours:
  RPC: do this; done.
  DUMP: give me all of these things; here you go
  EVENT; tell me about these events; here’s one …. Here’s one…. Oh here’s
         another….. etc.

RPC and DUMP commands are handled synchronously. Therefore on return from
OM::write(…) VPP has been issued with the request and responded. EVENTs are
asynchronous and will be delivered to the listeners in a different thread – so
beware!!

* As such VOM provides some level of insulation to the changes to the VPP
  binary API.
** some of the type names are shorten for brevity’s sake.

*/
namespace VOM {
/**
 * The interface to writing objects into VPP OM.
 */
class OM
{
public:
  /**
   * A class providing the RAII pattern for mark and sweep
   */
  class mark_n_sweep
  {
  public:
    /**
     * Constructor - will call mark on the key
     */
    mark_n_sweep(const client_db::key_t& key);

    /**
     * Destructor - will call sweep on the key
     */
    ~mark_n_sweep();

  private:
    /**
     * no copies
     */
    mark_n_sweep(const mark_n_sweep& ms) = delete;

    /**
     * The client whose state we are guarding.
     */
    client_db::key_t m_key;
  };

  /**
   * Init
   */
  static void init();

  /**
   * populate the OM with state read from HW.
   */
  static void populate(const client_db::key_t& key);

  /**
   * Mark all state owned by this key as stale
   */
  static void mark(const client_db::key_t& key);

  /**
   * Sweep all the key's objects that are stale
   */
  static void sweep(const client_db::key_t& key);

  /**
   * Replay all of the objects to HW.
   */
  static void replay(void);

  /**
   * Make the State in VPP reflect the expressed desired state.
   *  But don't call the HW - use this whilst processing dumped
   *  data from HW
   */
  template <typename OBJ>
  static rc_t commit(const client_db::key_t& key, const OBJ& obj)
  {
    rc_t rc = rc_t::OK;

    HW::disable();
    rc = OM::write(key, obj);
    HW::enable();

    return (rc);
  }

  /**
   * Make the State in VPP reflect the expressed desired state.
   *  After processing all the objects in the queue, in FIFO order,
   *  any remaining state owned by the client_db::key_t is purged.
   * This is a template function so the object's update() function is
   * always called with the derived type.
   */
  template <typename OBJ>
  static rc_t write(const client_db::key_t& key, const OBJ& obj)
  {
    rc_t rc = rc_t::OK;

    /*
     * Find the singular instance another owner may have created.
     * this always returns something.
     */
    std::shared_ptr<OBJ> inst = obj.singular();

    /*
     * Update the existing object with the new desired state
     */
    inst->update(obj);

    /*
     * Find if the object already stored on behalf of this key.
     * and mark them stale
     */
    object_ref_list& objs = m_db->find(key);

    /*
     * Iterate through this list to find a matchin' object
     * to the one requested.
     */
    auto match_ptr = [inst](const object_ref& oref) {
      return (inst == oref.obj());
    };
    auto it = std::find_if(objs.begin(), objs.end(), match_ptr);

    if (it != objs.end()) {
      /*
       * yes, this key already owns this object.
       */
      it->clear();
    } else {
      /*
       * Add the singular instance to the owners list
       */
      objs.insert(object_ref(inst));
    }

    return (HW::write());
  }

  /**
   * Remove all object in the OM referenced by the key
   */
  static void remove(const client_db::key_t& key);

  /**
   * Print each of the object in the DB into the stream provided
   */
  static void dump(const client_db::key_t& key, std::ostream& os);

  /**
   * Print each of the KEYS
   */
  static void dump(std::ostream& os);

  /**
   * Class definition for listeners to OM events
   */
  class listener
  {
  public:
    listener() = default;
    virtual ~listener() = default;

    /**
     * Handle a populate event
     */
    virtual void handle_populate(const client_db::key_t& key) = 0;

    /**
     * Handle a replay event
     */
    virtual void handle_replay() = 0;

    /**
     * Get the sortable Id of the listener
     */
    virtual dependency_t order() const = 0;

    /**
     * less than operator for set sorting
     */
    bool operator<(const listener& listener) const
    {
      return (order() < listener.order());
    }
  };

  /**
   * Register a listener of events
   */
  static bool register_listener(listener* listener);

private:
  /**
   * Database of object state created for each key
   */
  static client_db* m_db;

  /**
   * Comparator to keep the pointers to listeners in sorted order
   */
  struct listener_comparator_t
  {
    bool operator()(const listener* l1, const listener* l2) const
    {
      return (l1->order() < l2->order());
    }
  };

  /**
   * convenient typedef for the sorted set of listeners
   */
  typedef std::multiset<listener*, listener_comparator_t> listener_list;

  /**
   * The listeners for events
   */
  static std::unique_ptr<listener_list> m_listeners;
};
}

/*
 * fd.io coding-style-patch-verification: ON
 *
 * Local Variables:
 * eval: (c-set-style "mozilla")
 * End:
 */

#endif