Commit 18721848 authored by Millian Poquet's avatar Millian Poquet

Documentation

parent f23e8717
......@@ -242,7 +242,7 @@ TCL_SUBST =
# members will be omitted, etc.
# The default value is: NO.
OPTIMIZE_OUTPUT_FOR_C = YES
OPTIMIZE_OUTPUT_FOR_C = NO
# Set the OPTIMIZE_OUTPUT_JAVA tag to YES if your project consists of Java or
# Python sources only. Doxygen will then generate output that is more tailored
......@@ -409,7 +409,7 @@ LOOKUP_CACHE_SIZE = 0
# normally produced when WARNINGS is set to YES.
# The default value is: NO.
EXTRACT_ALL = YES
EXTRACT_ALL = NO
# If the EXTRACT_PRIVATE tag is set to YES, all private members of a class will
# be included in the documentation.
......@@ -730,7 +730,7 @@ WARN_IF_DOC_ERROR = YES
# parameter documentation, but not about the absence of documentation.
# The default value is: NO.
WARN_NO_PARAMDOC = NO
WARN_NO_PARAMDOC = YES
# The WARN_FORMAT tag determines the format of the warning messages that doxygen
# can produce. The string should contain the $file, $line, and $text tags, which
......@@ -793,7 +793,7 @@ RECURSIVE = NO
# Note that relative paths are relative to the directory from which doxygen is
# run.
EXCLUDE =
EXCLUDE = cmake old schedulers repeater.py
# The EXCLUDE_SYMLINKS tag can be used to select whether or not files or
# directories that are symbolic links (a Unix file system feature) are excluded
......
/**
* @file batsim.cpp
* @brief Batsim's entry point
*/
#include <string>
#include <stdio.h>
......@@ -24,14 +29,17 @@
using namespace std;
XBT_LOG_NEW_DEFAULT_CATEGORY(batsim, "batsim");
XBT_LOG_NEW_DEFAULT_CATEGORY(batsim, "batsim"); //!< Logging
/**
* @brief Batsim verbosity level
*/
enum class VerbosityLevel
{
QUIET,
NETWORK_ONLY,
INFORMATION,
DEBUG
QUIET //!< Almost nothing should be displayed
,NETWORK_ONLY //!< Only network messages should be displayed
,INFORMATION //!< Informations should be displayed (default)
,DEBUG //!< Debug informations should be displayed too
};
/**
......@@ -39,22 +47,22 @@ enum class VerbosityLevel
*/
struct MainArguments
{
std::string platformFilename; //! The SimGrid platform filename
std::string workloadFilename; //! The JSON workload filename
std::string platformFilename; //!< The SimGrid platform filename
std::string workloadFilename; //!< The JSON workload filename
std::string socketFilename = "/tmp/bat_socket"; //! The Unix Domain Socket filename
std::string socketFilename = "/tmp/bat_socket"; //!< The Unix Domain Socket filename
std::string masterHostName = "master_host"; //! The name of the SimGrid host which runs scheduler processes and not user tasks
std::string exportPrefix = "out"; //! The filename prefix used to export simulation information
std::string masterHostName = "master_host"; //!< The name of the SimGrid host which runs scheduler processes and not user tasks
std::string exportPrefix = "out"; //!< The filename prefix used to export simulation information
bool energy_used = false; //! True if and only if the SimGrid energy plugin should be used.
VerbosityLevel verbosity = VerbosityLevel::INFORMATION; //! Sets the Batsim verbosity
bool allow_space_sharing = false; //! Allows/forbids space sharing. Two jobs can run on the same machine if and only if space sharing is allowed.
bool enable_simgrid_process_tracing = false; //! If set to true, this options enables the tracing of SimGrid processes
bool enable_schedule_tracing = true; //! If set to true, the schedule is exported to a Pajé trace file
bool energy_used = false; //!< True if and only if the SimGrid energy plugin should be used.
VerbosityLevel verbosity = VerbosityLevel::INFORMATION; //!< Sets the Batsim verbosity
bool allow_space_sharing = false; //!< Allows/forbids space sharing. Two jobs can run on the same machine if and only if space sharing is allowed.
bool enable_simgrid_process_tracing = false; //!< If set to true, this options enables the tracing of SimGrid processes
bool enable_schedule_tracing = true; //!< If set to true, the schedule is exported to a Pajé trace file
bool abort = false; //! A boolean value. If set to yet, the launching should be aborted for reason abortReason
std::string abortReason; //! Human readable reasons which explains why the launch should be aborted
bool abort = false; //!< A boolean value. If set to yet, the launching should be aborted for reason abortReason
std::string abortReason; //!< Human readable reasons which explains why the launch should be aborted
};
/**
......@@ -146,6 +154,12 @@ int parse_opt (int key, char *arg, struct argp_state *state)
return 0;
}
/**
* @brief Main function
* @param[in] argc The number of arguments
* @param[in] argv The arguments' values
* @return 0 on success, something else otherwise
*/
int main(int argc, char * argv[])
{
MainArguments mainArgs;
......
/**
* @file context.hpp The Batsim context
* @file context.hpp
* @brief The Batsim context
*/
#pragma once
......@@ -11,22 +12,25 @@
#include "export.hpp"
#include "pstate.hpp"
/**
* @brief The Batsim context
*/
struct BatsimContext
{
UnixDomainSocket socket;
Machines machines;
Jobs jobs;
Profiles profiles;
PajeTracer paje_tracer;
PStateChangeTracer pstate_tracer;
CurrentSwitches current_switches;
UnixDomainSocket socket; //!< The UnixDomainSocket
Machines machines; //!< The machines
Jobs jobs; //!< The jobs
Profiles profiles; //!< The profiles
PajeTracer paje_tracer; //!< The PajeTracer
PStateChangeTracer pstate_tracer; //!< The PStateChangeTracer
CurrentSwitches current_switches; //!< The current switches
long long microseconds_used_by_scheduler = 0;
bool energy_used;
bool smpi_used;
bool allow_space_sharing;
bool trace_schedule;
std::string platform_filename;
std::string workload_filename;
std::string export_prefix;
long long microseconds_used_by_scheduler = 0; //!< The number of microseconds used by the scheduler
bool energy_used; //!< Stores whether the energy part of Batsim should be used
bool smpi_used; //!< Stores whether SMPI should be used
bool allow_space_sharing; //!< Stores whether space sharing (using the same machines to compute different jobs) should be allowed
bool trace_schedule; //!< Stores whether the resulting schedule should be outputted
std::string platform_filename; //!< The name of the platform file
std::string workload_filename; //!< The name of the workload file
std::string export_prefix; //!< The output export prefix
};
......@@ -20,7 +20,7 @@
using namespace std;
XBT_LOG_NEW_DEFAULT_CATEGORY(export, "export");
XBT_LOG_NEW_DEFAULT_CATEGORY(export, "export"); //!< Logging
WriteBuffer::WriteBuffer(const std::string & filename, int bufferSize)
: bufferSize(bufferSize)
......@@ -481,7 +481,8 @@ void PajeTracer::hsvToRgb(double h, double s, double v, double & r, double & g,
}
}
void exportJobsToCSV(const string &filename, const BatsimContext *context)
void exportJobsToCSV(const std::string &filename, const BatsimContext *context)
{
ofstream f(filename, ios_base::trunc);
xbt_assert(f.is_open(), "Cannot write file '%s'", filename.c_str());
......@@ -528,7 +529,7 @@ void exportJobsToCSV(const string &filename, const BatsimContext *context)
}
void exportScheduleToCSV(const string &filename, double scheduling_time, const BatsimContext *context)
void exportScheduleToCSV(const std::string &filename, double scheduling_time, const BatsimContext *context)
{
ofstream f(filename, ios_base::trunc);
xbt_assert(f.is_open(), "Cannot write file '%s'", filename.c_str());
......
......@@ -50,10 +50,10 @@ public:
void flushBuffer();
private:
std::ofstream f; //! The file stream on which the buffer is outputted
const int bufferSize; //! The buffer maximum size
char * buffer = nullptr;//! The buffer
int bufferPos = 0; //! The current position of the buffer (previous positions are already written)
std::ofstream f; //!< The file stream on which the buffer is outputted
const int bufferSize; //!< The buffer maximum size
char * buffer = nullptr; //!< The buffer
int bufferPos = 0; //!< The current position of the buffer (previous positions are already written)
};
/**
......@@ -214,37 +214,35 @@ private:
void shuffleColors();
private:
const char * rootType = "root_ct";
const char * machineType = "machine_ct";
const char * machineState = "machine_state";
const char * schedulerType = "scheduler_ct";
const char * killerType = "killer_ct";
const char * killEventKiller = "kk";
const char * killEventMachine = "km";
const char * utilizationVarType = "vu_vt";
const char * mstateWaiting = "w";
const char * mstateLaunching = "l";
//const char * varGlobalUtilization = "vgu";
const char * root = "root";
const char * scheduler = "sc";
const char * killer = "k";
const char * machinePrefix = "m";
const char * jobPrefix = "j";
const char * waitingColor= "\"0.0 0.0 0.0\"";
const char * launchingColor = "\"0.3 0.3 0.3\"";
const char * utilizationColor = "\"0.0 0.5 0.0\"";
const bool _logLaunchings;
WriteBuffer * _wbuf = nullptr;
std::map<int, std::string> _jobs;
std::vector<std::string> _colors;
PajeTracerState state = UNINITIALIZED;
const char * rootType = "root_ct"; //!< The root type output name
const char * machineType = "machine_ct"; //!< The machine type output name
const char * machineState = "machine_state"; //!< The machine state output name
const char * schedulerType = "scheduler_ct"; //!< The scheduler type output name
const char * killerType = "killer_ct"; //!< The killer type output name
const char * killEventKiller = "kk"; //!< The kill event (on the Killer) output name
const char * killEventMachine = "km"; //!< The kill event (on machines) output name
const char * utilizationVarType = "vu_vt"; //!< The utilization variable type output name
const char * mstateWaiting = "w"; //!< The waiting state output name
const char * mstateLaunching = "l"; //!< The launching state output name
const char * root = "root"; //!< The Pajé root output name
const char * scheduler = "sc"; //!< The scheduler output name
const char * killer = "k"; //!< The killer output name
const char * machinePrefix = "m"; //!< The machine output prefix
const char * jobPrefix = "j"; //!< The job output prefix
const char * waitingColor= "\"0.0 0.0 0.0\""; //!< The color used for idle machines
const char * launchingColor = "\"0.3 0.3 0.3\""; //!< The color used for machines launching a job
const char * utilizationColor = "\"0.0 0.5 0.0\""; //!< The color used for the utilization graph
const bool _logLaunchings; //!< If set to true, job launchings should be outputted (in addition to starting decisions)
WriteBuffer * _wbuf = nullptr; //!< The buffer class used to handle the output file
std::map<int, std::string> _jobs; //!< Maps job numbers to their Pajé representation
std::vector<std::string> _colors; //!< Strings associated with colors, used for the jobs
PajeTracerState state = UNINITIALIZED; //!< The state of the PajeTracer
};
......@@ -279,5 +277,5 @@ public:
void add_pstate_change(double time, int machine_id, int pstate_after);
private:
WriteBuffer * _wbuf = nullptr;
WriteBuffer * _wbuf = nullptr; //!< The buffer used to handle the output file
};
/**
* @file ipp.cpp
* @brief Inter-Process Protocol
* @brief Inter-Process Protocol (within Batsim, not with the Decision real process)
*/
#include "ipp.hpp"
......@@ -9,7 +9,7 @@
using namespace std;
XBT_LOG_NEW_DEFAULT_CATEGORY(ipp, "ipp");
XBT_LOG_NEW_DEFAULT_CATEGORY(ipp, "ipp"); //!< Logging
void send_message(const std::string & destination_mailbox, IPMessageType type, void * data)
{
......
/**
* @file ipp.hpp
* @brief Inter-Process Protocol
* @brief Inter-Process Protocol (within Batsim, not with the Decision real process)
*/
#pragma once
......@@ -40,7 +40,7 @@ enum class IPMessageType
*/
struct JobSubmittedMessage
{
int job_id; //! The job ID
int job_id; //!< The job ID
};
/**
......@@ -48,7 +48,7 @@ struct JobSubmittedMessage
*/
struct JobCompletedMessage
{
int job_id; //! The job ID
int job_id; //!< The job ID
};
/**
......@@ -56,7 +56,7 @@ struct JobCompletedMessage
*/
struct JobRejectedMessage
{
int job_id; //! The job ID
int job_id; //!< The job ID
};
/**
......@@ -64,9 +64,9 @@ struct JobRejectedMessage
*/
struct SchedulingAllocation
{
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
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
};
/**
......@@ -74,7 +74,7 @@ struct SchedulingAllocation
*/
struct SchedulingAllocationMessage
{
std::vector<SchedulingAllocation *> allocations; //! Possibly several allocations
std::vector<SchedulingAllocation *> allocations; //!< Possibly several allocations
};
/**
......@@ -82,8 +82,8 @@ struct SchedulingAllocationMessage
*/
struct PStateModificationMessage
{
MachineRange machine_ids; //! The IDs of the machines on which the pstate should be changed
int new_pstate; //! The power state into which the machines should be put
MachineRange machine_ids; //!< The IDs of the machines on which the pstate should be changed
int new_pstate; //!< The power state into which the machines should be put
};
/**
......@@ -91,7 +91,7 @@ struct PStateModificationMessage
*/
struct NOPMeLaterMessage
{
double target_time;
double target_time; //!< The time at which Batsim should send a NOP message to the decision real process
};
/**
......@@ -99,8 +99,8 @@ struct NOPMeLaterMessage
*/
struct SwitchONMessage
{
int machine_id;
int new_pstate;
int machine_id; //!< The unique number of the machine which should be switched ON
int new_pstate; //!< The power state the machine should be put into
};
/**
......@@ -108,8 +108,8 @@ struct SwitchONMessage
*/
struct SwitchOFFMessage
{
int machine_id;
int new_pstate;
int machine_id; //!< The unique number of the machine which should be switched OFF
int new_pstate; //!< The power state the machine should be put into
};
/**
......@@ -117,9 +117,13 @@ struct SwitchOFFMessage
*/
struct IPMessage
{
/**
* @brief Destroys a IPMessage
* @details This method deletes the message data according to its type
*/
~IPMessage();
IPMessageType type; //! The message type
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.
IPMessageType type; //!< The message type
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.
};
/**
......@@ -127,8 +131,8 @@ struct IPMessage
*/
struct RequestReplyProcessArguments
{
BatsimContext * context;
std::string send_buffer;
BatsimContext * context; //!< The BatsimContext
std::string send_buffer; //!< The message to send to the Decision real process
};
/**
......@@ -136,7 +140,7 @@ struct RequestReplyProcessArguments
*/
struct ServerProcessArguments
{
BatsimContext * context;
BatsimContext * context; //!< The BatsimContext
};
/**
......@@ -144,8 +148,8 @@ struct ServerProcessArguments
*/
struct ExecuteJobProcessArguments
{
BatsimContext * context;
SchedulingAllocation * allocation;
BatsimContext * context; //!< The BatsimContext
SchedulingAllocation * allocation; //!< The SchedulingAllocation
};
/**
......@@ -153,8 +157,8 @@ struct ExecuteJobProcessArguments
*/
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
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
};
/**
......@@ -162,9 +166,9 @@ struct KillerProcessArguments
*/
struct SwitchPStateProcessArguments
{
BatsimContext * context;
int machine_id;
int new_pstate;
BatsimContext * context; //!< The BatsimContext
int machine_id; //!< The unique number of the machine whose power state should be switched
int new_pstate; //!< The power state into which the machine should be put
};
/**
......@@ -172,7 +176,7 @@ struct SwitchPStateProcessArguments
*/
struct JobSubmitterProcessArguments
{
BatsimContext * context;
BatsimContext * context; //!< The BatsimContext
};
/**
......@@ -180,7 +184,7 @@ struct JobSubmitterProcessArguments
*/
struct WaiterProcessArguments
{
double target_time;
double target_time; //!< The time at which the waiter should stop waiting
};
/**
......
/**
* @file job_submitter.hpp
* @brief Job submitter
* @file job_submitter.cpp
* @brief Contains functions related to job submission
*/
#include "job_submitter.hpp"
......
/**
* @file job_submitter.hpp
* @brief Job submitter
* @brief Contains functions related to job submission
*/
#pragma once
......
......@@ -22,7 +22,7 @@
using namespace std;
using namespace rapidjson;
XBT_LOG_NEW_DEFAULT_CATEGORY(jobs, "jobs");
XBT_LOG_NEW_DEFAULT_CATEGORY(jobs, "jobs"); //!< Logging
Jobs::Jobs()
{
......
......@@ -32,18 +32,18 @@ enum class JobState
*/
struct Job
{
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; //! 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
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; //!< 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
};
/**
......@@ -121,6 +121,6 @@ public:
const std::map<int, Job*> & jobs() const;
private:
std::map<int, Job*> _jobs; //! The std::map which contains the jobs
Profiles * _profiles; //! The profiles associated with the jobs
std::map<int, Job*> _jobs; //!< The std::map which contains the jobs
Profiles * _profiles; //!< The profiles associated with the jobs
};
......@@ -11,7 +11,7 @@
#include <simgrid/msg.h>
#include <smpi/smpi.h>
XBT_LOG_NEW_DEFAULT_CATEGORY(jobs_execution, "jobs_execution");
XBT_LOG_NEW_DEFAULT_CATEGORY(jobs_execution, "jobs_execution"); //!< Logging
using namespace std;
......@@ -47,7 +47,7 @@ int smpi_replay_process(int argc, char *argv[])
}
int execute_profile(BatsimContext *context,
const string & profile_name,
const std::string & profile_name,
const SchedulingAllocation * allocation,
double *remaining_time)
{
......
/**
* @file machine_range.cpp
* @brief Contains the class which handles set of machines
*/
#include "machine_range.hpp"
#include <vector>
......@@ -7,7 +12,7 @@
#include <simgrid/msg.h>
XBT_LOG_NEW_DEFAULT_CATEGORY(machine_range, "machine_range");
XBT_LOG_NEW_DEFAULT_CATEGORY(machine_range, "machine_range"); //!< Logging
using namespace std;
......
......@@ -211,5 +211,5 @@ public:
static MachineRange from_string_hyphen(const std::string & str, const std::string & sep = ",", const std::string & joiner = "-", const std::string & error_prefix = "Invalid machine range string");
private:
Set set; //! The internal set of machines
Set set; //!< The internal set of machines
};
......@@ -18,7 +18,7 @@
using namespace std;
XBT_LOG_NEW_DEFAULT_CATEGORY(machines, "machines");
XBT_LOG_NEW_DEFAULT_CATEGORY(machines, "machines"); //!< Logging
Machines::Machines()
{
......
......@@ -40,14 +40,14 @@ struct Machine
*/
~Machine();
int id; //! The machine unique number
std::string name; //! The machine name
msg_host_t host; //! The SimGrid host corresponding to the machine
MachineState state; //! The current state of the Machine
std::set<int> jobs_being_computed; //! The set of jobs being computed on the Machine
int id; //!< The machine unique number
std::string name; //!< The machine name
msg_host_t host; //!< The SimGrid host corresponding to the machine
MachineState state; //!< The current state of the Machine
std::set<int> jobs_being_computed; //!< The set of jobs being computed on the Machine
std::map<int, PStateType> pstates; //! Maps power state number to their power state type
std::map<int, SleepPState *> sleep_pstates; //! Maps sleep power state numbers to their SleepPState
std::map<int, PStateType> pstates; //!< Maps power state number to their power state type
std::map<int, SleepPState *> sleep_pstates; //!< Maps sleep power state numbers to their SleepPState
/**
* @brief Returns whether the Machine has the given power state
......@@ -174,9 +174,9 @@ public:
long double total_consumed_energy(const BatsimContext * context) const;
private:
std::vector<Machine *> _machines; //! The vector of computing machines
Machine * _masterMachine = nullptr; //! The Master host
PajeTracer * _tracer = nullptr; //! The PajeTracer
std::vector<Machine *> _machines; //!< The vector of computing machines
Machine * _masterMachine = nullptr; //!< The Master host
PajeTracer * _tracer = nullptr; //!< The PajeTracer
};
/**
......
......@@ -20,7 +20,7 @@
#include "context.hpp"
#include "ipp.hpp"
XBT_LOG_NEW_DEFAULT_CATEGORY(network, "network");
XBT_LOG_NEW_DEFAULT_CATEGORY(network, "network"); //!< Logging
using namespace std;
......
......@@ -77,8 +77,8 @@ public:
void send(const std::string & message);
private:
int _server_socket = -1; //! The server-side socket
int _client_socket = -1; //! The client-side socket
int _server_socket = -1; //!< The server-side socket
int _client_socket = -1; //!< The client-side socket
};
/**
......
/**
* @file profiles.cpp
* Contains profile-related structures and classes
* @brief Contains profile-related structures and classes
*/
#include "profiles.hpp"
......@@ -17,7 +17,7 @@ using namespace std;
using namespace rapidjson;
using namespace boost;
XBT_LOG_NEW_DEFAULT_CATEGORY(profiles, "profiles");
XBT_LOG_NEW_DEFAULT_CATEGORY(profiles, "profiles"); //!< Logging
Profiles::Profiles()