reporter.hpp

一个非常好的人工智能开发工具开源软件

/***
 *** See the file "L2_RTI_EO1/disclaimers-and-notices-L2.txt" for 
 *** information on usage and redistribution of this file, 
 *** and for a DISCLAIMER OF ALL WARRANTIES.
 ***/
#ifndef REPORTER_HPP
#define REPORTER_HPP

#include <iostream.h>             // for iostream
#include "SCL2L2Interface.h"
#include "TelemetryEncoding.hpp"

class Assignment;
class Candidate;
class Livingstone;
class Variable;

/**
 * The client L2Task invokes the Reporter API when its
 * RTIMessage argument specifies a REPORT_* operation.
 * L2Task extracts the arguments and passes them unmodified.
 * The Reporter queries Livingstone for time steps, Variable values and
 * Candidates. When reporting diagnoses, it installs Candidates and reports
 * the resulting values of Variables.
 * The reporter sends three kinds of output:
 * (1) it traces its operations to a trace stream
 * (2) it logs its operations by invoking a logger
 * (3) it enqueues Candidate and mode packets to SCL
 */

class Reporter {
public:

  /**
   * The punctuation that separates values in "L2_MSG_TYPE::str". It is a
   * C string rather than a char to permit variable length.
   */
  static const char* SEPARATOR;

  /**
   * The maximum number of characters allowed in "L2_MSG_TYPE::str", rounded
   * up generously.
   */
  static const unsigned int MSGSIZ;

  /**
   * Open a file for trace output.
   * \param livingstone a reference to the L2 engine for querying. It is not
   * const because Candidates are installed.
   */
  Reporter(Livingstone& livingstone);

  /** Close the trace output file. */
  ~Reporter();

  /**
   * Report that a command was issued to L2.
   * \param seconds the whole seconds part of the time stamp
   * \param nanosec the nanoseconds part of the time stamp
   * \param variableID the ID of the Command Variable
   * \param valueIndex the index of the Command Variable's value
   */
  void reportCommand(unsigned seconds,
		     unsigned nanosec,
		     int variableID,
		     int valueIndex);

  /**
   * Report the results of the most recent find-candidates operation.
   * \param seconds the whole seconds part of the time stamp
   * \param nanosec the nanoseconds part of the time stamp
   */
  void reportDiagnosis(unsigned seconds,
		       unsigned nanosec);

  /** Report that a find-candidates operation was sent to L2. */
  void reportFindCandidates();

  /**
   * Report that an observation was sent to L2.
   * \param seconds the whole seconds part of the time stamp
   * \param nanosec the nanoseconds part of the time stamp
   * \param variableID the ID of the Observable Variable
   * \param valueIndex the index of the Observable's Variable's value
   */
  void reportObservation(unsigned seconds,
			 unsigned nanosec,
			 int variableID,
			 int valueIndex);

  /**
   * Report that an idle progress (null command) was issued to L2.
   * \param seconds the whole seconds part of the time stamp
   * \param nanosec the nanoseconds part of the time stamp
   */
  void reportIdle(unsigned seconds,
		  unsigned nanosec);

  /** Report that a find-candidates operation was requested. */
  void findCandidates();

  /** A no-op; probably unimplemented. */
  void reportFullState();

private:

  /** An attribute-value pair to hold variable-value assignments. */
  typedef struct {
    /** The Livingstone 2 variable ID. */
    unsigned variableID;
    /** The Livingstone 2 variable value index. */
    int valueIndex;
  } AVP;

  /**
   * Place the Assignment into the telemetry packet.
   * \param timeStep the time step of the Candidate's Assignment's Variable
   * \param variableID the ID of the Candidate's Assignment's Variable
   * \param valueIndex the value index of the Candidate's Assignment's Variable
   * \param weight the weight of the Assignment
   */
  void packetizeAssignment(unsigned timeStep,
			   unsigned variableID,
			   unsigned valueIndex,
			   unsigned weight);

  /**
   * Send an Assignment, one element of a Candidate.
   * \param assignment an Assignment
   */
  void assignment(const Assignment& assignment);

  /**
   * Send the value of a Variable after a Candidate has been installed.
   * \param timeStep the Variable's time step
   * \param variableID the ID of the Observable Variable
   * \param valueIndex the index of the Observable's Variable's value
   * \param variableType an enum
   */
  void assumption(unsigned timeStep,
		  unsigned variableID,
		  unsigned valueIndex,
		  VariableType variableType);

  /**
   * Send data about the Candidate to the report streams.
   * \param candidate a Candidate
   */
  void reportCandidate(const Candidate& candidate);


  /**
   * Install the Candidate and report its modes.
   * \param candidate a Candidate
   */
  void reportCandidateModes(const Candidate& candidate,
			    unsigned seconds,
			    unsigned nanosec);

  /**
   * Begin sending a Candidate, one element of a diagnosis.
   * \param candidateIndex a serial enumerator, not the offset within the
   * set of Candidates
   */
  void beginCandidate(unsigned candidateIndex);

  /** Punctuation to end a Candidate. */
  void endCandidate();

  /**
   * Begin sending the results of a diagnosis.
   * \param seconds the whole seconds part of the time stamp
   * \param nanosec the nanoseconds part of the time stamp
   */
  void beginDiagnose(unsigned seconds,
		     unsigned nanosec);

  /** Punctuation to end the results of a diagnosis. */
  void endDiagnose();

  /**
   * Associate a local time step to the time stamp.
   * \param seconds the whole seconds part of the time stamp
   * \param nanosec the nanoseconds part of the time stamp
   */
  void reportTimeStep(unsigned seconds,
		      unsigned nanosec);

  /**
   * Enqueue the message with the appropriate opcode.
   * \param message the message string
   */
  void send(const char* message);

  /**
   * Send an Assignment to the StateVariable, one element of a Candidate.
   * \param assignment an Assignment
   */
  void stateVariableAssignment(const Assignment& assignment);

  /**
   * Map a Variable onto its VariableType.
   * \param variable a Variable
   * \return the input argument's VariableType
   */
  static VariableType variableType(const Variable& variable);

  /**
   * Make the telemetry packet clean for re-use.
   * \param seconds time stamp seconds
   * \param nanosec time stamp nanoseconds
   * \param candidate is this a set of Candidates (vs. a set of modes)?
   */
  void initializeL2ResultMsg(int seconds, int nanosec, bool candidate);

  /**
   * Pack Assignment information into an unsigned long int.
   * \param variableID the Variable ID of the Assignment
   * \param valueIndex the value index of the Assignment
   * \param weight the weight of the Assignment
   * \return the 3 input arguments packed into a long int
   */
  static unsigned long encodeAssignment(unsigned int variableID,
					unsigned int valueIndex,
					unsigned int weight);

  /**
   * Pack mode Assignment information into an unsigned short int.
   * \param variableID the Variable ID of the Assignment
   * \param valueIndex the value index of the Assignment
   * \return the 2 input arguments packed into a short int
   */
  static unsigned short encodeModeAssignment(unsigned int variableID,
					     unsigned int valueIndex);

  /** Enqueue the L2ResultMsg. */
  void sendPacketToSCL();

  /** Have the modes been identified and placed in d_sentModeAssignments? */
  bool modesEnumerated() const;

  /** Identify the modes and place them in d_sentModeAssignments. */
  void enumerateModes();

  /** A reference to the L2 engine. */
  Livingstone& d_livingstone;

  /** For some reason, the Reporter maintains its own time step. */
  int d_localTimeStep;

  /** The telemetry packet. */
  L2ResultMsg d_l2ResultMsg;

  /** The index of the current Candidate. */
  unsigned d_candidateIndex;

  /** The index of the current Assignment within a Candidate. */
  unsigned d_assignmentIndex;

  /** The number of mode Variables. */
  unsigned d_modeCount;

  /** Set of sent mode assignments. */
  AVP d_sentModeAssignments[MAX_NUMBER_OF_MODES];

  void checkForFaults (void);

};


/**
 * Write a description of the L2ResultMsg to the output stream.
 * \param os an output stream
 * \param l2ResultMsg a telemetry packet
 * \param the os parameter
 */
ostream& operator<<(ostream& os, const L2ResultMsg& l2ResultMsg);

#endif // REPORTER_HPP