hlaobjectinstance.h

Go to the documentation of this file.

#ifndef HLA_OBJECT_INSTANCE_H_
#define HLA_OBJECT_INSTANCE_H_

#include "base/cleancontainers.h"
#include <queue>

#include "ftk.h"
#include "base/msftypes.h"

// forward declaration
class HLAObjectClass;
class InstanceClient;
class MessageClient;
class MethodMessage;

/**
 * This class represents an instance of an HLA object.
 * @ingroup ftk
 */
class HLAObjectInstance
{
  public:
    /** 
     * Constructor - creates an object instance of class @a clname.
     *
     * This constructor is used by a federate which wants to create
     * its own local objects in order to register them with the RFI
     * (by using RFI::registerObjectInstance()).
     *
     * @see               RFI::registerObjectInstance()
     */
    HLAObjectInstance (const char* clname);
      
    /** 
     * Contructor - creates an object instance having an object handle
     * and an HLAObjectClass.
     *
     * This constructor is used by the Federate Ambassador when it
     * discovers an object and wants to add it to the local object list
     * (by using RFI::addObjectInstance()). 
     *
     * @see               RFI::addObjectInstance()
     */
    HLAObjectInstance (ftk::HANDLE objHandle, ftk::HANDLE classHandle);

    /** 
     * Destructor.
     *
     * Does some cleaning and removes the object instance from the
     * federation. 
     */
    virtual ~HLAObjectInstance (void);

    /** 
     * Removes this object from the Federation. 
     */
    void removeFromFederation (void);

    /** 
     * Returns the class (HLAObjectClass) of the object instance.
     */
    HLAObjectClass* getObjectClass (void);

    /** 
     * Returns the class handle for this object instance. 
     */
    ftk::HANDLE classHandleGet (void);
      
    /** 
     * Returns the class name of this object instance.
     */
    const char* classNameGet (void);

    /** 
     * Sets the handle for this object instance.
     * 
     * This should be done only by a method which get this handle
     * from the RTI. 
     */
    void handleSet (ftk::HANDLE id);

    /** 
     * Returns the handle for this object instance. 
     */
    ftk::HANDLE handleGet (void);

    /** 
     * Sets boolean defining whether or not this object has been 
     * discovered.
     *
     * @param d           @c true signifies that this object has been
     *                    discovered.
     *                    @c false signifies that this object has been
     *                    created by this federate.
     */
    void discovered (bool d);

    /** 
     * Tests whether or not this object has been discovered.
     *
     * @return            @c true if this object has been discovered by
     *                    the federate, @c false if this object was
     *                    created by the federate itself. 
     */
    bool discovered (void);

    /** Mark the instance as zombie or not. 
     * An instance is considered as zombie when it still exist in the LRC, but
     * not in the RTIexec database. This situation typically occurs after a 
     * reset. A zombie instance will not try to remove itself from the 
     * federation a destruction. */
    void zombie(bool z);

    /** Return the zombie state of the instance (see above method). */
    bool zombie();

    bool isAttributeInitialized(ftk::ATTRIBUTE_INDEX index);

    bool isAttributeInitialized(ftk::HANDLE h) {
  map<ftk::HANDLE, bool>::iterator it = initialized_attributes.find(h);
  if ( it != initialized_attributes.end() ) return (*it).second;
  else return false;
    }

    /** 
     * Returns the data corresponding to the given handle.
     *
     * This method is purely virtual and has to be implemented by 
     * derived classes which know about the queried data.
     *
     * @param h           attribute handle
     * @param data        reference to a pointer to a char buffer
     * @param size        the size of the buffer containing the desired
     *                    data
     * @warning           The caller of this function just provides a
     *                    pointer to the buffer. The memory for the data
     *                    should then be allocated. (In normal FTK usage
     *                    this is done by the XDRmessage.getBuffer(data)
     *                    call.) <b>But it is up to the caller to delete the
     *                    allocated memory.</b> 
     *
     * @see               HLAObjectInstance::processPendingUpdates() for
     *                    a correct example.
     */
    virtual bool getAttributeData (ftk::HANDLE h,
           char*& data, 
           unsigned int& size) = 0;

    /** 
     * Sets the data corresponding to a given handle.
     *
     * This method is purely virtual and has to be implemented by
     * derived classes: making this call causes the concerned sub-class
     * to set its correct data member (identified by h) with the given 
     * data.
     *
     * @param h           attribute handle
     * @param data        pointer to the buffer containing the data to
     *                    set
     * @param size        size of the data to set
     */
    virtual bool setAttributeData (ftk::HANDLE h,
           const char* data,
           unsigned int size) = 0;

    /** 
     * Pushes the request for an update for the attribute with the given
     * handle to a local queue.
     * Clients of this objectinstance will be notified that all updates
     * requests have been performed with the attributesInitialized callback.
     */
    // inline void queueAttributeRequest (ftk::HANDLE handle);
    void queueAttributeRequest (ftk::HANDLE handle);

    /** 
     * Pushes the action to update the attribute with the given handle to
     * a local queue. 
     */
    // inline void queueAttributeUpdate (ftk::HANDLE handle);
    void queueAttributeUpdate (ftk::HANDLE handle);

    /** 
     * Pushes the request to acquire the ownership of
     * the attribute with the given handle to a local queue. 
     * Clients of this objectinstance will be notified that all acquisitions
     * requests have been performed with the onwershipsAcquired callback.
     */
    // inline void queueAttributeAcquisition (ftk::HANDLE handle);
    void queueAttributeAcquisition (ftk::HANDLE handle);

    /** 
     * Pushes the action to release the ownership of 
     * the attribute with the given handle to a local queue. 
     */
    // inline void queueAttributeRelease (ftk::HANDLE handle);
    void queueAttributeRelease (ftk::HANDLE handle);

    /** 
     * Processes the pending update actions. 
     */
    int processPendingUpdates (void);

    /** 
     * Processes the pending update request(s). 
     */
    int processPendingRequests (void);

    /** 
     * Processes the pending ownership release(s). 
     */
    int processPendingReleases (void);

    /** 
     * Processes the pending ownership acquisitiions(s). 
     */
    int processPendingAcquisitions (void);

    /** 
     * Processes all the pending actions present in the local queues. 
     */
    int processPendings (unsigned char what);

    /** 
     * Sends a request for ownership of a given set of attributes to the
     * RTI.
     *
     * The attribute ownership acquisition is perfomed on the basis of 
     * the priority argument. The federate can acquire the attribute 
     * only if the given priority is higher than the priority that
     * the owning federate has given to this object class.
     */
    bool attributeOwnershipAcquisition (set<ftk::ATTRIBUTE_INDEX>& attr, 
          unsigned char priority);

    /** 
     * Unconditionally releases a set of attributes.
     */
    bool unconditionalAttributeOwnershipDivestiture (set<ftk::ATTRIBUTE_INDEX>& attr);
                   
    /** 
     * Sets a boolean defining whether or not an object is owned. 
     *
     * This call assigns the value of @c o to @b all the attributes
     * of this object.
     */
//       void owned (bool o);

    /** 
     * Tests whether or not the attribute with the given handle is owned
     * by the federate. 
     *
     * @return            @c true if the attribute is owned by the 
     *                    federate, @c false otherwise
     */
    bool attributeOwned (ftk::HANDLE h);

    /** 
     * Sets the boolean defining whether or not the attribute with the
     * given handle is owned by the federate. 
     */
    void attributeOwned (ftk::HANDLE h, bool o);

    /** Return the number of clients this object instance has. */
    size_t getNumberOfClients();

    /** Set a new client of this object instance. 
     * Return false if the client is already in the list, true otherwise 
     * (after insertion). */
    bool addClient(MessageClient *client);

    /** Remove a client from the list of this object instance. 
     * Return false if the client was not in the list, false otherwise
     * (after deletion). */
    bool removeClient(MessageClient *client);


    bool addClient(InstanceClient *client);

    bool removeClient(InstanceClient *client);

    void notifyRemoval(void);

    /** Return a pointer on the first client of this object instance. */
    MessageClient* getFirstClient();

    /** Return a pointer on the next client of this object instance. */
    MessageClient* getNextClient();

    /** 
     * Tests whether or not the object instance has been marked as 
     * identified.
     *
     * "Identified" means that all the necessary attributes to completely
     * identify this object instance have been initialized.
     */
    bool isIdentified (void) {
  return _identified;
    }

    /** Returns if the object is ready to use or not.
     * The significance of ready is application dependent.
     */
    bool isReady(void) {
  return _ready;
    }

    /** 
     * Tests whether or not this object instance has been fully
     * initialized. 
     *
     * @return            @c true when all the attributes of this object 
     *                    have received at least one valid update,
     *                    @c false otherwise.
     */
    bool isComplete (void) {
  return _complete;
    }

    /** 
     * Tests whether or not this object instance has been represented by
     * this federate.
     *
     * "Represented" could be used for any purpose by the federate. 
     * Normally it is used to determine if the federate has created a
     * specific object to represent/manage its HLA equivalent. 
     */
    bool isRepresented (void) {
  return _represented;
    }

    /** Set the object as represented. */
    void setRepresented (void) {
  _represented = true;
    }

    void setIdentifierAttribute (ftk::HANDLE h);

    void addReadyRequiredAttribute (ftk::HANDLE h);

    /** This method will be called when the instance has been identified.
     * This is to derived classes of HLAObjectInstance to initiate this call 
     * (for example when it receive an relection for an identifier). The
     * method should be implemented by derived classes.
     */
    virtual void identified(void)  { /* do nothing */ };

    /** This method will be called when the instance is ready to use by a 
     * specific federate.
     */
    virtual void ready(void)  { /* do nothing */ };

    /** This method will be called when all the attributes of this instance
     * have been initialized.
     * This method is called from the HLAObjectInstance level: developper 
     * of derived classes does not have to initiate this call, but can
     * implement the method itself.
     */
    virtual void complete(void) { /* do nothing */ };

#if defined(_MIPS_SIM)
// Suppress REMARK 3201: The parameter "h" was never referenced.
#pragma set woff 3201
#endif

    /** This method will be called when the federateambassador process
     * an attribute reflection. */
    virtual void reflect(ftk::HANDLE h) { /* do nothing */ };

    /** This method could be implemented by derived classes to handle
     * message attached to an instance. */
    virtual void messageReceived(MethodMessage* msg) { /* do nothing */ };

#if defined(_MIPS_SIM)
#pragma reset woff 3201
#endif

    /** Check if the attribute reflection satisfies any request and make
     * the object fully identified and propagate the attribute inside
     * the object and its clients. */
    void processReflection(ftk::HANDLE h);
      
    /** Check the status of pendinf acquisitions.
  Using the given handle, this method checks if after this ownership
  acquisition notification there is still pending acquisitions. If not,
  then the method will notify all clients that all the acquisitions
  requests have been satisfied (with onwershipsAcquired).
    */
    void checkPendingAcquisitions(ftk::HANDLE h);

    /** Set the full name of the entity */
    void nameSet(std::string name);

    /** Return the full name of the entity (with its hierachy).
  K9:HazCam:Physical -> K9:HazCam:Physical 
    */
    std::string nameGet() const;

    /** Return the short name of the entity.
  K9:HazCam:Physical -> Physical
    */
    std::string entityNameGet(void);
      
    /** Return the parent full name of the entity. 
  K9:HazCam:Physical -> K9:HazCam
    */
    std::string parentNameGet(void);
      
    /** Return the depth of the hierachy where this object is located.
  K9:HazCam:Physical -> 3
    */
    size_t hierachyLevelGet(void);
      
    /** Return the name of the parent at the given level.
  (K9:HazCam:Physical,1) -> K9
  (K9:HazCam:Physical,2) -> HazCam
  (K9:HazCam:Physical,3) -> Physical
    */
    std::string nameLevelGet(size_t level);
      
    virtual void print(ostream& w = cout);
    //##Documentation
    //## Set the time of the attribute update.
    void setAttributeTimestamp(
        //##Documentation
        //## RTI handle of the attribute
        ftk::HANDLE attributeHandle, 
        //##Documentation
        //## Time of the update.
        double timeStamp);


    //##Documentation
    //## Return the time of the most recent update or -1
    //## if there is no time stamp.
    double getAttributeTimestamp(
        //##Documentation
        //## RTI handle of the desired attribute.
        ftk::HANDLE attributeHandle);

  protected:
    /** 
     * Marks the attribute with the given handle as initialized, then
     * checks if all the attributes have been initialized, and if so,
     * marks this object as initialized.
     * @todo: This method should go in the private section and allow only
     * ftkfederateambassador to call it...
     */
    void checkInitializedAttributes (ftk::HANDLE h);
      
    /** Check the status of the pending updates.
  Using the given handle, this method checks if after this update
  there is still pending updates. If not, then the method will
  notify all clients that all the update requests have been
  satisfied (with attributesInitialized).
    */ 
    void checkPendingUpdates(ftk::HANDLE h);

    /** Pointer to the class of this object */
    HLAObjectClass* _objectClassPtr;

    /** The handle of this object instance (defined by the RTI). */
    ftk::HANDLE _objectHandle;

    /** full name of this object instance.
  this name should be unique among the  federation.
  this name contains the hierachy of objects. */
    std::string _name;

    /** name of the object instance without the full hierachy. */
    std::string _entityName;

    /** Full name of the parent of this object instance. */
    std::string _parentName;

    /** Depth of the hierachy */
    size_t _hierarchyLevel;

    /** A queue of the attributes to update.
     * This queue is needed because the RTI is not reentrant. Then if the 
     * federateAmbassador receive a request to update an attribute, then
     * the application can not call right away a method to the rtiAmbassador
     * to provide the requested update: the federateAmbassador put 
     * this update request in a queue which will then be processed outside
     * the federateAmbassador and then avoid the reentrant call to the RTI.
     * @todo              Continue comment editing from this point [MDW]
     */
    set<ftk::HANDLE> attributes2update;

    /** A queue of the attribute for which this object require updates. */
    queue<ftk::HANDLE> attributes2request;

    /** A queue of the attributes to release.
     * This queue is needed for the same reason than attributes2update.
     * In this case, we maintain a queue of all the attributes for which 
     * this federate should release the ownership. */
    queue<ftk::HANDLE> attributes2release;

    /** A queue of the attributes to acquire. */
    queue<ftk::HANDLE> attributes2acquire;

    /** This map maintained a list of the status of each attributes 
     * regarding their ownership.
     * A @c true value associated with a attribute handle means that this
     * attribute is owned by this federate, a @c false value mean that it 
     * is not owned by this federate. */
    map<ftk::HANDLE, bool> owned_attributes;

    /** List of clients of this message instance. */
    list<MessageClient*> _msgClients;

    /** Last returned client. */
    list<MessageClient*>::iterator _currentClient;

    list<InstanceClient*> _objClients;

    void markAttributeInitialized(ftk::HANDLE h);
      
  private:
    /** Define if this object been discovered (@ c true) or created by this
     * federate (@c false) */
    bool _discovered;

    /** Flag to store if this object instance is identified or not. */
    bool _identified;

    /** Flag to store if this object instance is ready to be used or not. */
    bool _ready;

    /** Flag to store if this object has been fully initialized or not */
    bool _complete;

    /** Flag to store if this object instance has been represented or not. */
    bool _represented;

    bool _zombie;

    /** This method extract information from the name: entityName, 
  parentName and hierachyLevel. */
    void parseName(void);      

    /** Handle of the attribute marking the instance as identified. */
    ftk::HANDLE _identifierHandle;

    /** Set of handles marking the instance as ready.*/
    set<ftk::HANDLE> _readyRequiredHandles;

    /** Map to store if the attributes of this object instance have 
     * been initialized or not. */
    map<ftk::HANDLE, bool> initialized_attributes;

    set<ftk::HANDLE> _pendingUpdates;
    set<ftk::HANDLE> _pendingAcquisitions;
    map<ftk::HANDLE,double> _timeStamps;


};

#endif // HLA_OBJECT_INSTANCE_H_

---