simulator-agent.h 3.85 KB
Newer Older
1 2
/*
 * EMULAB-COPYRIGHT
3
 * Copyright (c) 2004, 2005 University of Utah and the Flux Group.
4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32
 * All rights reserved.
 */

/**
 * @file simulator-agent.h
 *
 * Header file for the SIMULATOR agent.
 */

#ifndef _simulator_agent_h
#define _simulator_agent_h

#include "event-sched.h"
#include "local-agent.h"
#include "error-record.h"

#ifdef __cplusplus
extern "C" {
#endif

/**
 * Enumeration of the different categories of text in a report.
 */
typedef enum {
	SA_RDK_MESSAGE,	/*< Main message body, this is at the top of the report
			 and is intended for a plain english description of
			 the experiment. */
	SA_RDK_LOG,	/*< Log data for the tail of the report, used for
			  machine generated data mostly. */
33
	SA_RDK_CONFIG,	/*< Config data for the tail of the report. */
34 35 36 37

	SA_RDK_MAX	/*< The maximum number of message types. */
} sa_report_data_kind_t;

38
enum {
39 40 41 42 43 44 45 46 47
	SA_RDB_NEWLINE,
};

enum {
	SA_RDF_NEWLINE = (1L << SA_RDB_NEWLINE),
};

enum {
	SAB_TIME_STARTED,
48 49 50 51
	SAB_STABLE,
};

enum {
52
	SAF_TIME_STARTED = (1L << SAB_TIME_STARTED),
53 54 55
	SAF_STABLE = (1L << SAB_STABLE),
};

56 57 58 59 60
/**
 * A local agent structure for the NS Simulator object.
 */
struct _simulator_agent {
	struct _local_agent sa_local_agent;	/*< Local agent base. */
61
	unsigned long sa_flags;
62 63 64 65 66
	struct lnList sa_error_records;		/*< The error records that have
						  been collected over the
						  course of the experiment. */
	char *sa_report_data[SA_RDK_MAX];	/*< Different kinds of text to
						 include in the report. */
67
	struct timeval sa_time_start;		/*< */
68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92
};

/**
 * Pointer type for the _simulator_agent structure.
 */
typedef struct _simulator_agent *simulator_agent_t;

/**
 * Create a simulator agent and initialize it with the default values.
 *
 * @return An initialized simulator agent.
 */
simulator_agent_t create_simulator_agent(void);

/**
 * Check a simulator agent object against the following invariants:
 *
 * @li sa_local_agent is sane
 * @li sa_error_records is sane
 *
 * @param sa An initialized simulator agent object.
 * @return True.
 */
int simulator_agent_invariant(simulator_agent_t sa);

93 94 95 96 97 98 99 100 101 102 103 104
/**
 * Add some message/log data that should be included in the generated report
 * for this simulator.  The data is appended to any previous additions along
 * with a newline if it does not have one.
 *
 * @param sa The simulator agent object where the data is kept.
 * @param rdk The type of data being added.
 * @param data The data to add, should just be ASCII text.
 * @return Zero on success, -1 otherwise.
 *
 * @see send_report
 */
105 106
int add_report_data(simulator_agent_t sa,
		    sa_report_data_kind_t rdk,
107 108
		    char *data,
		    unsigned long flags);
109

110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134
/**
 * Sends a summary report to the user via e-mail and also sort of marks the end
 * of a run of the experiment.  The content of the report is partially
 * generated by the user with the rest being automatically generated by the
 * testbed.  First, the function will sync the logholes so any data needed to
 * automatically generate parts of the report are readily available.  Then, the
 * body of the mail is constructed by appending any user provided messages and
 * log data with the digested error records.  Ideally, the user provided
 * messages should provide a human readable summary of the success/failure of
 * their experiment.  Any log data from the user should report any performance
 * metrics, warnings, or any other salient data.  Finally, the function will
 * iterate through the list of error records and append any available log files
 * or messages paired with those records.
 *
 * After sending the mail, the simulator object will be reset to a pristine
 * state so another experimental run can begin with a clean slate.
 *
 * @param sa The simulator agent object to summarize.
 * @param args The event arguments.
 * @return Zero on success, -1 otherwise.
 *
 * @see dump_error_records
 */
int send_report(simulator_agent_t sa, char *args);

135 136 137 138 139
#ifdef __cplusplus
}
#endif

#endif