Commit 9174ce7a authored by Millian Poquet's avatar Millian Poquet

Documentation

parent 82f3aaa9
/**
* @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>
......
/**
* @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:
......
/**
* @file ipp.cpp
* @brief Inter-Process Protocol
*/
#include "ipp.hpp"
#include <simgrid/msg.h>
......
#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);
/**
* @file job_submitter.hpp
* @brief Job submitter
*/
#include "job_submitter.hpp"
#include <vector>
......
/**
* @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[]);
/**
* @file jobs.cpp
* @brief Contains job-related structures
*/
#include "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
};
/**
* @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];
......
/**
* @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[]);
......@@ -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)
......
/**
* @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);