PacketSet

Files CCore/inc/PacketSet.h CCore/src/PacketSet.cpp

PacketSet is a key class of the packet infra-structure. This class is a logical small pool of packets with a packet processing control and packet cancellation features. This class is used by packet originators.

template <class POD>
class PacketSet : public Funchor_nocopy
 {
   ....

  public:
  
   using ExtTop = PacketSetExt::ExtTop ; 

   // constructors
  
   explicit PacketSet(ulen max_packets=DefaultMaxPackets);
   
   explicit PacketSet(TextLabel name,ulen max_packets=DefaultMaxPackets);
   
   ~PacketSet();
   

The constructor argument name is used to name internal synchronization objects.

The argument max_packet is the packet limit. You cannot have more than max_packet active packets from this packet set ("external" packets are not counted).

PacketSet destructor performs the cancel_and_wait() operation. It also waits until all "external" packets are completed.

   // own list
   
   Packet<POD> try_get(); 
   
   Packet<POD> get(); // may return 0
   
   Packet<POD> get(TimeScope time_scope); 
   
   Packet<POD> get(MSec timeout); 
   
   Packet<POD> try_get_short(); 
   
   Packet<POD> get_short(); // never return 0 
   
   Packet<POD> get_short(TimeScope time_scope); 
   
   Packet<POD> get_short(MSec timeout); 

Packet get methods. They have the same semantic, as the correspondent packet pool methods. Packets are taken from the default packet pool. The packet set limits the number of active packets by the max_packet. All taken packets are remembered in the internal packet list, so it is possible cancel them or wait for completion.

   
   void cancel_and_wait();
   
   bool wait(TimeScope time_scope);
   
   bool wait(MSec timeout);

cancel_and_wait() cancels all active packets and then waits indefinitely until they are completed ("external" packets are not included).

wait() waits until all active packets are completed ("external" packets are not included) or up to timeout expired. The return value is true, if the first case happens. If the timeout expires, then wait() performs the cancel_and_wait() operation.

   
   // external list
   
   Packet<POD> try_get(ExtTop &ext_list); 
   
   Packet<POD> get(ExtTop &ext_list); // may return 0
   
   Packet<POD> get(ExtTop &ext_list,TimeScope time_scope); 
   
   Packet<POD> get(ExtTop &ext_list,MSec timeout); 
   
   Packet<POD> try_get_short(ExtTop &ext_list); 
   
   Packet<POD> get_short(ExtTop &ext_list); // never return 0 
   
   Packet<POD> get_short(ExtTop &ext_list,TimeScope time_scope); 
   
   Packet<POD> get_short(ExtTop &ext_list,MSec timeout); 
   

Packet get method with an external packet list. You may use an additional external packet list, represented by an object of type PacketSet::ExtTop, when getting a packet from the packet set. You may use this list further to cancel all packets from this list.

   void cancel(ExtTop &ext_list);
   
   class Cancel : NoCopy
    {
      PacketSet<POD> &pset;
      ExtTop cancel_list;
      
     public:
     
      explicit Cancel(PacketSet<POD> &pset_) : pset(pset_) {}
      
      void build(ExtTop &ext_list) { pset.buildCancel(ext_list,cancel_list); }
      
      void cancel() { DoCancel(cancel_list); }
    };

cancel(ExtTop &ext_list) cancels all packets from the given external list.

Using the inner class Cancel, you can cancel packets from the given external list or several such lists in two phase. The method build() cancels packets from the given external list and collects them into the working list. Then the method cancel() calls cancel functions of collected packets.

   // external packets 
   
   Packet<POD> enlist(Packet<POD> packet);
  
   Packet<POD> enlist(ExtTop &ext_list,Packet<POD> packet);
 };

"External" packets may be included in cancellation operations of the packet set. The method enlist() is to do this. You may specify an external packet list also. "External" packets are not included in waiting operations. Only the PacketSet destructor waits for their completion.