Documentation

export.cpp

+/**
+ * @file export.cpp
+ * @brief Batsim's export classes and functions
+ * @details Contains the classes and functions which are related to Batsim's exports.
+ */
+
 #include "export.hpp"
 
 #include <algorithm>

export.hpp

+/**
+ * @file export.hpp
+ * @brief Batsim's export classes and functions
+ * @details Contains the classes and functions which are related to Batsim's exports.
+ */
+
 #pragma once
 
 #include <stdio.h>
@@ -13,6 +19,9 @@
 
 struct BatsimContext;
 
+/**
+ * @brief Buffered-write output file
+ */
 class WriteBuffer
 {
 public:
@@ -106,8 +115,25 @@ public:
      */
     void addJobLaunching(int jobID, const std::vector<int> & usedMachineIDs, double time);
 
+    /**
+     * @brief Created a job in the Pajé output file
+     * @param jobID The job unique number
+     */
     void register_new_job(int jobID);
+
+    /**
+     * @brief Sets a machine in the idle state
+     * @param machineID The unique machine number
+     * @param time The time at which the machine should be marked as idle
+     */
     void set_machine_idle(int machineID, double time);
+
+    /**
+     * @brief Sets a machine in the computing state
+     * @param machineID The unique machine number
+     * @param jobID The unique job number that the machine computes
+     * @param time The time at which the machine should be marked as computing the job
+     */
     void set_machine_as_computing_job(int machineID, int jobID, double time);
 
     /**
@@ -225,14 +251,34 @@ private:
 };
 
 
-
+/**
+ * @brief Traces how power states are changed over time
+ */
 class PStateChangeTracer
 {
 public:
+    /**
+     * @brief Constructs a PStateChangeTracer
+     */
     PStateChangeTracer();
+
+    /**
+     * @brief Sets the output filename of the tracer
+     * @param filename The name of the output file of the tracer
+     */
     void setFilename(const std::string & filename);
+
+    /**
+     * @brief Destroys a PStateChangeTracer
+     */
     ~PStateChangeTracer();
 
+    /**
+     * @brief Adds a power state change in the tracer
+     * @param time The time at which the change occurs
+     * @param machine_id The unique machine number
+     * @param pstate_after The power state the machine will be in after the given time
+     */
     void add_pstate_change(double time, int machine_id, int pstate_after);
 
 private:

ipp.cpp

+/**
+ * @file ipp.cpp
+ * @brief Inter-Process Protocol
+ */
+
 #include "ipp.hpp"
 
 #include <simgrid/msg.h>

ipp.hpp

-#pragma once
-
 /**
- * @file ipp.hpp Inter-Process Protocol
+ * @file ipp.hpp
+ * @brief Inter-Process Protocol
  */
 
+#pragma once
+
 #include <vector>
 #include <string>
 
@@ -13,6 +14,9 @@
 
 struct BatsimContext;
 
+/**
+ * @brief Stores the different types of inter-process messages
+ */
 enum class IPMessageType
 {
     JOB_SUBMITTED           //!< Submitter -> Server. The submitter tells the server a new job has been submitted.
@@ -31,56 +35,86 @@ enum class IPMessageType
     ,SWITCHED_OFF           //!< SwitcherOFF -> Server. The switcherOFF process tells the server the machine pstate has been changed.
 };
 
+/**
+ * @brief The content of the JobSubmitted message
+ */
 struct JobSubmittedMessage
 {
     int job_id; //! The job ID
 };
 
+/**
+ * @brief The content of the JobCompleted message
+ */
 struct JobCompletedMessage
 {
     int job_id; //! The job ID
 };
 
+/**
+ * @brief The content of the JobRejected message
+ */
 struct JobRejectedMessage
 {
     int job_id; //! The job ID
 };
 
+/**
+ * @brief A subpart of the SchedulingAllocation message
+ */
 struct SchedulingAllocation
 {
-    int job_id;
+    int job_id; //! The job unique number
     MachineRange machine_ids; //! The IDs of the machines on which the job should be allocated
     std::vector<msg_host_t> hosts;  //! The corresponding SimGrid hosts
 };
 
+/**
+ * @brief The content of the JobSubmitted message
+ */
 struct SchedulingAllocationMessage
 {
     std::vector<SchedulingAllocation *> allocations;  //! Possibly several allocations
 };
 
+/**
+ * @brief The content of the PstateModification message
+ */
 struct PStateModificationMessage
 {
     MachineRange machine_ids; //! The IDs of the machines on which the pstate should be changed
     int new_pstate; //! The pstate the machines should be put into
 };
 
+/**
+ * @brief The content of the NOPMeLater message
+ */
 struct NOPMeLaterMessage
 {
     double target_time;
 };
 
+/**
+ * @brief The content of the SwitchON message
+ */
 struct SwitchONMessage
 {
     int machine_id;
     int new_pstate;
 };
 
+/**
+ * @brief The content of the SwitchOFF message
+ */
 struct SwitchOFFMessage
 {
     int machine_id;
     int new_pstate;
 };
 
+/**
+ * @brief The base struct sent in inter-process messages
+ */
 struct IPMessage
 {
     ~IPMessage();
@@ -88,29 +122,44 @@ struct IPMessage
     void * data;        //! The message data (can be NULL if type is in [SCHED_NOP, SUBMITTER_HELLO, SUBMITTER_BYE, SUBMITTER_READY]). Otherwise, it is either a JobSubmittedMessage*, a JobCompletedMessage* or a SchedulingAllocationMessage* according to type.
 };
 
+/**
+ * @brief The arguments of the request_reply_scheduler_process process
+ */
 struct RequestReplyProcessArguments
 {
     BatsimContext * context;
     std::string send_buffer;
 };
 
+/**
+ * @brief The arguments of the uds_server_process process
+ */
 struct ServerProcessArguments
 {
     BatsimContext * context;
 };
 
+/**
+ * @brief The arguments of the execute_job_process process
+ */
 struct ExecuteJobProcessArguments
 {
     BatsimContext * context;
     SchedulingAllocation * allocation;
 };
 
+/**
+ * @brief The arguments of the killer_process process
+ */
 struct KillerProcessArguments
 {
     msg_task_t task; //! The task that will be cancelled if the walltime is reached
     double walltime; //! The number of seconds to wait before cancelling the task
 };
 
+/**
+ * @brief The arguments of the switch_on_machine_process and switch_off_machine_process processes
+ */
 struct SwitchPStateProcessArguments
 {
     BatsimContext * context;
@@ -118,11 +167,17 @@ struct SwitchPStateProcessArguments
     int new_pstate;
 };
 
+/**
+ * @brief The arguments of the job_submitter_process process
+ */
 struct JobSubmitterProcessArguments
 {
     BatsimContext * context;
 };
 
+/**
+ * @brief The arguments of the waiter_process process
+ */
 struct WaiterProcessArguments
 {
     double target_time;
@@ -136,6 +191,19 @@ struct WaiterProcessArguments
  * @param[in] data The data associated to the message
  */
 void send_message(const std::string & destination_mailbox, IPMessageType type, void * data = nullptr);
+
+/**
+ * @brief Sends a message from the given process to the given mailbox
+ * @param[in] dst The destination mailbox
+ * @param[in] type The type of message to send
+ * @param[in] job_id The job the message is about
+ * @param[in] data The data associated to the message
+ */
 void send_message(const char * destination_mailbox, IPMessageType type, void * data = nullptr);
 
+/**
+ * @brief Transforms a IPMessageType into a std::string
+ * @param[in] type The IPMessageType
+ * @return The std::string corresponding to the type
+ */
 std::string ipMessageTypeToString(IPMessageType type);

job_submitter.cpp

+/**
+ * @file job_submitter.hpp
+ * @brief Job submitter
+ */
+
 #include "job_submitter.hpp"
 
 #include <vector>

job_submitter.hpp

+/**
+ * @file job_submitter.hpp
+ * @brief Job submitter
+ */
+
 #pragma once
 
+/**
+ * @brief The process in charge of submitting jobs
+ * @param argc The number of arguments
+ * @param argv The argument values
+ * @return 0
+ */
 int job_submitter_process(int argc, char *argv[]);

jobs.cpp

 /**
  * @file jobs.cpp
+ * @brief Contains job-related structures
  */
 
 #include "jobs.hpp"

jobs.hpp

 /**
  * @file jobs.hpp
+ * @brief Contains job-related structures
  */
 
 #pragma once
@@ -13,6 +14,9 @@
 
 class Profiles;
 
+/**
+ * @brief Contains the different states a job can be in
+ */
 enum class JobState
 {
      JOB_STATE_NOT_SUBMITTED          //!< The job exists but cannot be scheduled yet.
@@ -23,44 +27,100 @@ enum class JobState
     ,JOB_STATE_REJECTED               //!< The job has been rejected by the scheduler.
 };
 
+/**
+ * @brief Represents a job
+ */
 struct Job
 {
-    int id;
-    std::string profile;
-    double submission_time;
-    double walltime;
-    int required_nb_res;
+    int id; //! The unique job number
+    std::string profile; //! The job profile name. The corresponding profile tells how the job should be computed
+    double submission_time; //! The job submission time: The time at which the becomes available
+    double walltime; //! The job walltime: if the job is executed for more than this amount of time, it will be killed
+    int required_nb_res; //! The number of resources the job is requested to be executed on
 
     long double consumed_energy; //! The sum, for each machine on which the job has been allocated, of the consumed energy (in Joules) during the job execution time (consumed_energy_after_job_completion - consumed_energy_before_job_start)
 
-    double starting_time;
-    double runtime;
-    MachineRange allocation;
-    JobState state;
+    double starting_time; //! The time at which the job starts to be executed.
+    double runtime; //! The amount of time during which the job has been executed
+    MachineRange allocation; //! The machines on which the job has been executed.
+    JobState state; //! The current state of the job
 };
 
+/**
+ * @brief Compares job thanks to their submission times
+ * @param[in] a The first job
+ * @param[in] b The second job
+ * @return True if and only if the first job's submission time is lower than the second job's submission time
+ */
 bool job_comparator_subtime(const Job * a, const Job * b);
 
+/**
+ * @brief Stores all the jobs of a workload
+ */
 class Jobs
 {
 public:
+    /**
+     * @brief Constructs an empty Jobs
+     */
     Jobs();
+    /**
+     * @brief Destroys a Jobs
+     */
     ~Jobs();
 
+    /**
+     * @brief Sets the profiles which are associated to the Jobs
+     * @param[in] profiles The profiles
+     */
     void setProfiles(Profiles * profiles);
 
+    /**
+     * @brief Loads the jobs from a JSON document
+     * @param[in] doc The JSON document
+     * @param[in] filename The name of the file the JSON document has been extracted from
+     */
     void load_from_json(const rapidjson::Document & doc, const std::string & filename);
 
+    /**
+     * @brief Accesses one job thanks to its unique number
+     * @param[in] job_id The job unique number
+     * @return A pointer to the job associated to the given job number
+     */
     Job * operator[](int job_id);
+
+    /**
+     * @brief Accesses one job thanks to its unique number (const version)
+     * @param[in] job_id The job unique number
+     * @return A (const) pointer to the job associated to the given job number
+     */
     const Job * operator[](int job_id) const;
+
+    /**
+     * @brief Allows to know whether a job exists
+     * @param[in] job_id The unique job number
+     * @return True if and only if a job with the given job number exists
+     */
     bool exists(int job_id) const;
+
+    /**
+     * @brief Allows to know whether the Jobs contains any SMPI job
+     * @return True if the number of SMPI jobs in the Jobs is greater than 0.
+     */
     bool containsSMPIJob() const;
 
+    /**
+     * @brief Displays the contents of the Jobs class (debug purpose)
+     */
     void displayDebug() const;
 
+    /**
+     * @brief Returns a copy of the std::map which contains the jobs
+     * @return A copy of the std::map which contains the jobs
+     */
     const std::map<int, Job*> & jobs() const;
 
 private:
-    std::map<int, Job*> _jobs;
-    Profiles * _profiles;
+    std::map<int, Job*> _jobs; //! The std::map which contains the jobs
+    Profiles * _profiles; //! The profiles associated with the jobs
 };

jobs_execution.cpp

+/**
+ * @file jobs_execution.cpp
+ * @brief Contains functions related to the execution of the jobs
+ */
+
 #include "jobs_execution.hpp"
 #include "jobs.hpp"
 
@@ -43,7 +48,7 @@ int smpi_replay_process(int argc, char *argv[])
 
 int execute_profile(BatsimContext *context,
                     const string & profile_name,
-                    SchedulingAllocation *allocation,
+                    const SchedulingAllocation * allocation,
                     double *remaining_time)
 {
     Job * job = context->jobs[allocation->job_id];

jobs_execution.hpp

+/**
+ * @file jobs_execution.hpp
+ * @brief Contains functions related to the execution of the jobs
+ */
+
 #pragma once
 
 #include "ipp.hpp"
 #include "context.hpp"
 
+/**
+ * @brief The process in charge of killing a job if it reaches its walltime
+ * @param argc The number of arguments
+ * @param argv The arguments' values
+ * @return 0
+ */
 int killer_process(int argc, char *argv[]);
+
+/**
+ * @brief The process in charge of executing a SMPI job
+ * @param argc The number of arguments
+ * @param argv The arguments's values
+ * @return 0
+ */
 int smpi_replay_process(int argc, char *argv[]);
 
+/**
+ * @brief Executes the profile of a job
+ * @param[in] context The Batsim Context
+ * @param[in] profile_name The name of the profile to execute
+ * @param[in] allocation The machines the job should be executed on
+ * @param[in,out] remaining_time The remaining amount of time before walltime
+ * @return 0
+ */
 int execute_profile(BatsimContext * context,
                     const std::string & profile_name,
-                    SchedulingAllocation * allocation,
+                    const SchedulingAllocation * allocation,
                     double * remaining_time);
 
+/**
+ * @brief The process in charge of executing a job
+ * @param[in] argc The number of arguments
+ * @param[in] argv The arguments' values
+ * @return 0
+ */
 int execute_job_process(int argc, char *argv[]);
 
+/**
+ * @brief The process in charge of waiting for a given amount of time (related to the NOPMeLater message)
+ * @param[in] argc The number of arguments
+ * @param[in] argv The arguments' values
+ * @return 0
+ */
 int waiter_process(int argc, char *argv[]);

machine_range.cpp

@@ -6,6 +6,7 @@
 
 #include <simgrid/msg.h>
 
+
 XBT_LOG_NEW_DEFAULT_CATEGORY(machine_range, "machine_range");
 
 using namespace std;
@@ -54,6 +55,7 @@ MachineRange::Set::const_iterator MachineRange::intervals_end() const
 void MachineRange::clear()
 {
     set.clear();
+    xbt_assert(size() == 0);
 }
 
 void MachineRange::insert(const MachineRange &range)

machine_range.hpp

+/**
+ * @file machine_range.hpp
+ * @brief Contains the class which handles set of machines
+ */
+
 #pragma once
 
 #include <string>
@@ -5,56 +10,206 @@
 #include <boost/icl/interval_set.hpp>
 #include <boost/icl/closed_interval.hpp>
 
+/**
+ * @brief Handles a set of machines
+ */
 struct MachineRange
 {
 public:
+    /**
+     * @brief Represents a closed interval between two bounds.
+     */
     typedef boost::icl::closed_interval<int, std::less> ClosedInterval;
+    /**
+     * @brief Represents a Set of ClosedInterval
+     */
     typedef boost::icl::interval_set<int,
         ICL_COMPARE_INSTANCE(ICL_COMPARE_DEFAULT, int),
         ClosedInterval> Set;
 
 public:
+    /**
+     * @brief Returns an element_iterator corresponding to the beginning of the MachineRange
+     * @return An element_iterator corresponding to the beginning of the MachineRange
+     */
     Set::element_iterator elements_begin();
+
+    /**
+     * @brief Returns an element_const_iterator corresponding to the beginning of the MachineRange
+     * @return An element_const_iterator corresponding to the beginning of the MachineRange
+     */
     Set::element_const_iterator elements_begin() const;
 
+    /**
+     * @brief Returns an element_iterator corresponding to the ending of the MachineRange
+     * @return An element_iterator corresponding to the ending of the MachineRange
+     */
     Set::element_iterator elements_end();
+
+    /**
+     * @brief Returns an element_const_iterator corresponding to the ending of the MachineRange
+     * @return An element_const_iterator corresponding to the ending of the MachineRange
+     */
     Set::element_const_iterator elements_end() const;
 
+    /**
+     * @brief Returns an interval iterator corresponding to the beginning of the MachineRange
+     * @return An interval iterator corresponding to the beginning of the MachineRange
+     */
     Set::iterator intervals_begin();
+
+    /**
+     * @brief Returns an interval const_iterator corresponding to the beginning of the MachineRange
+     * @return An interval const_iterator corresponding to the beginning of the MachineRange
+     */
     Set::const_iterator intervals_begin() const;
 
+    /**
+     * @brief Returns an interval iterator corresponding to the ending of the MachineRange
+     * @return An interval iterator corresponding to the ending of the MachineRange
+     */
     Set::iterator intervals_end();
+
+    /**
+     * @brief Returns an interval const_iterator corresponding to the ending of the MachineRange
+     * @return An interval const_iterator corresponding to the ending of the MachineRange
+     */
     Set::const_iterator intervals_end() const;
 
+    /**
+     * @brief Clears the MachineRange: After this call, it will be empty
+     */
     void clear();
+
+    /**
+     * @brief Inserts a MachineRange into another MachineRange
+     * @param[in] range The MachineRange to insert
+     */
     void insert(const MachineRange & range);
+
+    /**
+     * @brief Inserts a ClosedInterval into a MachineRange
+     * @param[in] interval The interval to insert
+     */
     void insert(ClosedInterval interval);
+
+    /**
+     * @brief Inserts a value (a single machine) into a MachineRange
+     * @param[in] value The value (the single machine) to insert
+     */
     void insert(int value);
 
+    /**
+     * @brief Removes a MachineRange from another MachineRange
+     * @param[in] range The MachineRange to remove
+     */
     void remove(const MachineRange & range);
+
+    /**
+     * @brief Removes a ClosedInterval from a MachineRange
+     * @param[in] interval The ClosedInterval to remove
+     */
     void remove(ClosedInterval interval);
-    void remove(int value);
 
-    MachineRange left(int nb_machines) const;
+    /**
+     * @brief Removes a value (a single machine) from a MachineRange
+     * @param value The value (the single machine) to remove
+     */
+    void remove(int value);
 
+    /**
+     * @brief Returns the first element of the MachineRange
+     * @return The first element of the MachineRange
+     */
     int first_element() const;
+
+    /**
+     * @brief Returns the number of machines in the MachineRange
+     * @return The number of machines in the MachineRange
+     */
     unsigned int size() const;
+
+    /**
+     * @brief Returns whether a machine is in the MachineRange
+     * @param[in] machine_id The machine
+     * @return True if and only if the the given machine is in the MachineRange
+     */
     bool contains(int machine_id) const;
 
+    /**
+     * @brief Returns a std::string corresponding to the MachineRange
+     * @details For example, with default values, the MachineRange {1,2,3,7} would be outputted as "[1,3]∪[7]"
+     * @param[in] union_str The union string
+     * @param[in] opening_bracket The opening_bracket string
+     * @param[in] closing_bracket The closing_bracket string
+     * @param[in] sep The separator string
+     * @return A std::string corresponding to the MachineRange
+     */
     std::string to_string_brackets(const std::string & union_str = "∪", const std::string & opening_bracket = "[", const std::string & closing_bracket = "]", const std::string & sep = ",") const;
+    /**
+     * @brief Returns a std::string corresponding to the MachineRange
+     * @details For example, with default values, the MachineRange {1,2,3,7} would be outputted as "1-3,7"
+     * @param[in] sep The separator string
+     * @param[in] joiner The joiner string
+     * @return A std::string corresponding to the MachineRange
+     */
     std::string to_string_hyphen(const std::string & sep = ",", const std::string & joiner = "-") const;
+
+    /**
+     * @brief Returns a std::string corresponding to the MachineRange
+     * @details For example, with default values, the MachineRange {1,2,3,7} would be outputted as "1,2,3,7"
+     * @param sep The separator string
+     * @return A std::string corresponding to the MachineRange
+     */
     std::string to_string_elements(const std::string & sep = ",") const;
 
+    /**
+     * @brief Sets the set of a MachineRange such that it is equal to the set of another MachineRange
+     * @param[in] other The other MachineRange
+     * @return The current MachineRange after the operation
+     */
     MachineRange & operator=(const MachineRange & other);
+
+    /**
+     * @brief Sets the set of a MachineRange such that it is equal to another ClosedInterval
+     * @param[in] interval The ClosedInterval
+     * @return The current MachineRange after the operation
+     */
     MachineRange & operator=(const MachineRange::ClosedInterval & interval);
 
+    /**
+     * @brief Returns whether a MachineRange is equal to another MachineRange
+     * @param[in] other The other MachineRange
+     * @return True if and only if the two MachineRange contain the same machines
+     */
     bool operator==(const MachineRange & other);