src/vpp-api/vom/om.hpp - fdio/vpp - Gitiles

 /*
  * 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
	/*
	* 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