Commit b8096fc1 authored by Millian Poquet's avatar Millian Poquet

Documentation

parent 3ce112a5
......@@ -30,10 +30,12 @@ XBT_LOG_NEW_CATEGORY(network, "Network");
#include "utils.h"
#include "export.h"
//! The total number of microseconds used by the external scheduler
long long microseconds_used_by_scheduler = 0;
//! The maximum length of the messages sent to the external scheduler
const int schedMessageMaxLength = 1024*1024 - 1; // 1 Mio should be enough...
//! Associates names to struct e_task_type_t
char *task_type2str[] =
{
"FINALIZE",
......@@ -48,6 +50,12 @@ char *task_type2str[] =
"SUBMITTER_BYE"
};
/**
* @brief Compares two machines in function of their name (lexicographic order)
* @param[in] e1 The first machine
* @param[in] e2 The second machine
* @return An integer less than, equal to, or greater than zero if e1 is found, respectively, to be less than, to match, or be greater than e2
*/
static int machine_comparator(const void * e1, const void * e2)
{
const msg_host_t * m1 = (msg_host_t *) e1;
......@@ -56,11 +64,13 @@ static int machine_comparator(const void * e1, const void * e2)
return strcmp(MSG_host_get_name(*m1), MSG_host_get_name(*m2));
}
//! The number of computing nodes
int nb_nodes = 0;
//! The computing nodes
msg_host_t *nodes;
//! The Unix Domain Socket file descriptor
int uds_fd = -1;
//! The PajeTracer object
PajeTracer * tracer = NULL;
// process functions
......@@ -70,23 +80,24 @@ static int launch_job(int argc, char *argv[]);
static void send_message(const char *dst, e_task_type_t type, int job_id, void *data);
/**
* \brief Send message through Unix Domain Socket
* @brief Sends a message on the Unix Domain Socket
* @param[in] msg The message to send
* @return 0
*/
static int send_uds(char *msg)
static int send_uds(char * msg)
{
int32_t lg = strlen(msg);
XBT_CINFO(network, "Sending '%s'", msg);
write(uds_fd, &lg, 4);
write(uds_fd, msg, lg);
//XBT_INFO("send_uds lg=%d, msg='%s'", lg, msg);
return 0;
}
/**
* \brief Receive message through Unix Domain Socket
* @brief Receives a message from the Unix Domain Socket
* @return The message (must be freed by the caller)
*/
static char *recv_uds()
{
int32_t lg;
......@@ -103,7 +114,10 @@ static char *recv_uds()
}
/**
* \brief Open Unix Domain Socket for communication with scheduler
* @brief Opens the Unix Domain Socket to communicate with the external scheduler
* @param[in] socketFilename The socket filename
* @param[in] nb_try The maximum number of connection attempts
* @param[in] msBetweenTries The delay (in milliseconds) between two connection tries
*/
static void open_uds(const char * socketFilename, int nb_try, double msBetweenTries)
{
......@@ -209,7 +223,11 @@ static int requestReplyScheduler(int argc, char *argv[])
}
/**
* \brief
* @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 *dst, e_task_type_t type, int job_id, void *data)
{
......@@ -228,13 +246,13 @@ void send_message(const char *dst, e_task_type_t type, int job_id, void *data)
}
/**
* \brief
* @brief Frees a task then makes it point to NULL
* @param[in, out] The task to free
*/
static void task_free(msg_task_t * task)
{
if(*task != NULL)
{
//xbt_free(MSG_task_get_data(*task));
MSG_task_destroy(*task);
*task = NULL;
}
......@@ -242,6 +260,8 @@ static void task_free(msg_task_t * task)
/**
* @brief The function in charge of job launching
* @param[in] argc The number of input arguments
* @param[in] argv The input arguments
* @return 0
*/
static int launch_job(int argc, char *argv[])
......@@ -283,7 +303,10 @@ static int launch_job(int argc, char *argv[])
}
/**
* \brief
* @brief The function executed on each computing node
* @param[in] argc The number of input arguments
* @param[in] argv The arguments
* @return 0
*/
static int node(int argc, char *argv[])
{
......@@ -624,7 +647,13 @@ int server(int argc, char *argv[])
}
/**
* \brief
* @brief Deploys the simulator
* @param[in] platform_file The SimGrid platform filename used in the simulation
* @param[in] masterHostName The name of the host which will be used for scheduling and not for computing jobs
* @param[in] pajeTraceFilename The name of the Pajé trace to generate
* @param[in] csvJobsFilename The name of the CSV output file about jobs
* @param[in] csvScheduleFilename The name of the CSV output file about the schedule
* @return The msg_error_t result of the inner call of MSG_main() (MSG_OK on success)
*/
msg_error_t deploy_all(const char *platform_file, const char * masterHostName, const char * pajeTraceFilename, const char * csvJobsFilename, const char * csvScheduleFilename)
{
......@@ -692,6 +721,9 @@ msg_error_t deploy_all(const char *platform_file, const char * masterHostName, c
return res;
}
/**
* @brief The main function arguments (a.k.a. program arguments)
*/
typedef struct s_main_args
{
char * platformFilename;//! The SimGrid platform filename
......@@ -708,6 +740,13 @@ typedef struct s_main_args
char * abortReason; //! Human readable reasons which explains why the launch should be aborted
} s_main_args_t;
/**
* @brief Used to parse the main parameters
* @param[in] key The current key
* @param[in] arg The current argument
* @param[in, out] state The current argp_state
* @return 0
*/
static int parse_opt (int key, char *arg, struct argp_state *state)
{
s_main_args_t * mainArgs = state->input;
......@@ -786,6 +825,12 @@ static int parse_opt (int key, char *arg, struct argp_state *state)
return 0;
}
/**
* @brief The main function (entry point of the program)
* @param[in] argc The number of input arguments
* @param[in] argv The input arguments
* @return 0 if the simulation run successfully, something else otherwise
*/
int main(int argc, char *argv[])
{
s_main_args_t mainArgs;
......
......@@ -7,19 +7,19 @@
*/
typedef enum
{
FINALIZE //! Server -> Node
,LAUNCH_JOB //! Server -> Node
,JOB_SUBMITTED //! Submitter -> Server
,JOB_COMPLETED //! Launcher/killer -> Server
,SCHED_EVENT //! SchedulerHandler -> Server
,SCHED_READY //! SchedulerHandler -> Server
,LAUNCHER_INFORMATION //! Node -> Launcher
,KILLER_INFORMATION //! Node -> Killer
,SUBMITTER_HELLO //! Submitter -> Server
,SUBMITTER_BYE //! Submitter -> Server
FINALIZE //!< Server -> Node. The server tells the node to stop its execution.
,LAUNCH_JOB //!< Server -> Node. The server tells the node to launch a new job.
,JOB_SUBMITTED //!< Submitter -> Server. The submitter tells the server a new job has been submitted.
,JOB_COMPLETED //!< Launcher/killer -> Server. The launcher or killer tells the server a job has been completed.
,SCHED_EVENT //!< SchedulerHandler -> Server. The scheduler handler tells the server a scheduling event occured.
,SCHED_READY //!< SchedulerHandler -> Server. The scheduler handler tells the server that the scheduler is ready (messages can be sent to it).
,LAUNCHER_INFORMATION //!< Node -> Launcher. The node gives launching information to the job launcher.
,KILLER_INFORMATION //!< Node -> Killer. The node gives killing information to the job killer.
,SUBMITTER_HELLO //!< Submitter -> Server. The submitter tells it starts submitting to the server.
,SUBMITTER_BYE //!< Submitter -> Server. The submitter tells it stops submitting to the server.
} e_task_type_t;
/*
/**
* @brief Data attached with the tasks used to communicate between MSG processes
*/
typedef struct s_task_data
......
......@@ -83,18 +83,21 @@ void writeBuffer_flush(WriteBuffer * wbuf)
// Since there is no module nor module-like (namespace, class) feature in C,
// Let's define some constants here
/**
* @brief Enumerates the different Pajé keywords
*/
enum PajeKeyword
{
PAJE_DEFINE_CONTAINER_TYPE = 1,
PAJE_CREATE_CONTAINER,
PAJE_DESTROY_CONTAINER,
PAJE_DEFINE_STATE_TYPE,
PAJE_DEFINE_ENTITY_VALUE,
PAJE_SET_STATE,
PAJE_DEFINE_EVENT_TYPE,
PAJE_NEW_EVENT,
PAJE_DEFINE_VARIABLE_TYPE,
PAJE_SET_VARIABLE,
PAJE_DEFINE_CONTAINER_TYPE = 1 //!< Defines a container type
,PAJE_CREATE_CONTAINER //!< Creates a container
,PAJE_DESTROY_CONTAINER //!< Destroys a container
,PAJE_DEFINE_STATE_TYPE //!< Defines a state type
,PAJE_DEFINE_ENTITY_VALUE //!< Define an entity value
,PAJE_SET_STATE //!< Sets a state
,PAJE_DEFINE_EVENT_TYPE //!< Defines an event type
,PAJE_NEW_EVENT //!< Creates an event
,PAJE_DEFINE_VARIABLE_TYPE //!< Defines a variable type
,PAJE_SET_VARIABLE //!< Set a variable
};
const char * PAJE_rootType = "root_ct";
......
......@@ -62,9 +62,9 @@ void exportScheduleToCSV(const char * filename, double scheduling_time);
*/
typedef enum
{
PAJE_STATE_UNINITIALIZED, //! The PajeTracer has not been initialized yet
PAJE_STATE_INITIALIZED, //! The PajeTracer has been initialized
PAJE_STATE_FINALIZED //! The PajeTracer has been finalized
PAJE_STATE_UNINITIALIZED //!< The PajeTracer has not been initialized yet
,PAJE_STATE_INITIALIZED //!< The PajeTracer has been initialized
,PAJE_STATE_FINALIZED //!< The PajeTracer has been finalized
} PajeTracerState;
/**
......
......@@ -16,6 +16,12 @@ typedef struct s_killer_delay_data
double walltime; //! The number of seconds to wait before cancelling the task
} KillerDelayData;
/**
* @brief The function used to kill jobs which exceed their walltime
* @param[in] argc The number of input arguments
* @param[in] argv The input arguments
* @return 0
*/
int killerDelay(int argc, char *argv[])
{
(void) argc;
......@@ -34,7 +40,6 @@ int killerDelay(int argc, char *argv[])
}
free(data);
return 0;
}
......
......@@ -12,17 +12,17 @@
#include <jansson.h> /* json parsing */
//XBT_LOG_NEW_DEFAULT_CATEGORY(batsim, "Batsim");
//! Enumerates the job states
typedef enum e_job_state
{
JOB_STATE_NOT_SUBMITTED //! The job exists but cannot be scheduled yet
,JOB_STATE_SUBMITTED //! The job has been submitted, it can now be scheduled
,JOB_STATE_RUNNING //! The job has been scheduled and is currently being processed
,JOB_STATE_COMPLETED_SUCCESSFULLY //! The job execution finished before its walltime
,JOB_STATE_COMPLETED_KILLED //! The job execution time was longer than its walltime so the job had been killed
JOB_STATE_NOT_SUBMITTED //!< The job exists but cannot be scheduled yet
,JOB_STATE_SUBMITTED //!< The job has been submitted, it can now be scheduled
,JOB_STATE_RUNNING //!< The job has been scheduled and is currently being processed
,JOB_STATE_COMPLETED_SUCCESSFULLY //!< The job execution finished before its walltime
,JOB_STATE_COMPLETED_KILLED //!< The job execution time was longer than its walltime so the job had been killed
} e_job_state_t;
//! The structure used to store a job
typedef struct s_job
{
int id; //! The job ID (as integer)
......@@ -38,6 +38,7 @@ typedef struct s_job
e_job_state_t state; //! The state
} s_job_t;
//! The structure used to store additional information about profiles of type msg_par
typedef struct s_msg_par
{
int nb_res; //! The number of resources
......@@ -45,12 +46,14 @@ typedef struct s_msg_par
double *com; //! The communication matrix
} s_msg_par_t;
//! The structure used to store additional information about profiles of type msg_par_hg
typedef struct s_msg_par_hg
{
double cpu; //! The computation amount on each node
double com; //! The communication amount between each pair of nodes
} s_msg_par_hg_t;
//! The structure used to store additional information about profiles of type composed
typedef struct s_composed_prof
{
int nb; //! The number of times the sequence must be repeated
......@@ -58,6 +61,7 @@ typedef struct s_composed_prof
char **seq; //! The sequence of profile names (array of char* of size lg_seq)
} s_composed_prof_t;
//! The structure used to store additional information about jobs of type delay
typedef struct s_delay
{
double delay;
......
......@@ -17,6 +17,12 @@ xbt_dict_t profiles = NULL;
xbt_dynar_t jobs_dynar = NULL;
xbt_dict_t job_id_to_dynar_pos = NULL;
/**
* @brief Compares two jobs according to their submission time
* @param[in] e1 The first job
* @param[in] e2 The second job
* @return An integer less than, equal to, or greater than zero if e1 is found, respectively, to be less than, to match, or be greater than e2
*/
static int job_submission_time_comparator(const void *e1, const void *e2)
{
const s_job_t * j1 = *(s_job_t **) e1;
......
......@@ -12,31 +12,93 @@
#include "job.h"
//! The structure used to store a profile
typedef struct s_profile
{
char * type;
void * data;
char * type; //! The profile type
void * data; //! The profile data
} s_profile_t, *profile_t;
// Global variables
//! The number of jobs
extern int nb_jobs;
//! The number of profiles
extern xbt_dict_t profiles;
//! The jobs dynamic array
extern xbt_dynar_t jobs_dynar;
//! The dictionary associating job IDs to their position in jobs_dynar
extern xbt_dict_t job_id_to_dynar_pos;
// Functions
/**
* @brief Converts a JSON number to a double
* @param[in] e The JSON node
* @return The double value corresponding to e
*/
double json_number_to_double(json_t *e);
/**
* @brief Loads the workload and the profiles from a given filename.
* @param[in] filename The filename
* @return The JSON root of what had been read (must be freed later)
*/
json_t *load_json_workload_profile(char *filename);
/**
* @brief Loads the jobs from a JSON root
* @param[in] root The JSON root
*/
void retrieve_jobs(json_t *root);
/**
* @brief Loads the profiles from a JSON root
* @param[in] root The JSON root
*/
void retrieve_profiles(json_t *root);
/**
* @brief Frees a profile
* @param[in,out] profile The profile
*/
void freeProfile(void * profile);
/**
* @brief Frees a job
* @param[in, out] job The job
*/
void freeJob(void * job);
/**
* @brief Initializes the job structures.
*/
void initializeJobStructures();
/**
* @brief Frees the job structures
*/
void freeJobStructures();
/**
* @brief Checks whether a job exist or not.
* @param[in] jobID The ID of the job to seek
* @return TRUE if the job exists, FALSE otherwise
*/
int jobExists(int jobID);
/**
* @brief Returns the job corresponding to a given job ID
* @param[in] jobID The job ID
* @return The job corresponding to jobID. The existence of the job is asserted in this function.
*/
s_job_t * jobFromJobID(int jobID);
/**
* @brief Checks whether jobs and profiles are valid or not
*/
void checkJobsAndProfilesValidity();
/**
* @brief Checks whether a profile exist or not
* @param[in] profileName The profile name
* @return TRUE if the profile exists, FALSE otherwise
*/
int profileExists(const char * profileName);
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment