// Copyright 2014 The Kyua Authors.
// All rights reserved.
//
// Redistribution and use in source and binary forms, with or without
// modification, are permitted provided that the following conditions are
// met:
//
// * Redistributions of source code must retain the above copyright
// notice, this list of conditions and the following disclaimer.
// * Redistributions in binary form must reproduce the above copyright
// notice, this list of conditions and the following disclaimer in the
// documentation and/or other materials provided with the distribution.
// * Neither the name of Google Inc. nor the names of its contributors
// may be used to endorse or promote products derived from this software
// without specific prior written permission.
//
// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
/// \file engine/scheduler.hpp
/// Multiprogrammed executor of test related operations.
///
/// The scheduler's public interface exposes test cases as "black boxes". The
/// handling of cleanup routines is completely hidden from the caller and
/// happens in two cases: first, once a test case completes; and, second, in the
/// case of abrupt termination due to the reception of a signal.
///
/// Hiding cleanup routines from the caller is an attempt to keep the logic of
/// execution and results handling in a single place. Otherwise, the various
/// drivers (say run_tests and debug_test) would need to replicate the handling
/// of this logic, which is tricky in itself (particularly due to signal
/// handling) and would lead to inconsistencies.
///
/// Handling cleanup routines in the manner described above is *incredibly
/// complicated* (insane, actually) as you will see from the code. The
/// complexity will bite us in the future (today is 2015-06-26). Switching to a
/// threads-based implementation would probably simplify the code flow
/// significantly and allow parallelization of the test case listings in a
/// reasonable manner, though it depends on whether we can get clean handling of
/// signals and on whether we could use C++11's std::thread. (Is this a to-do?
/// Maybe. Maybe not.)
///
/// See the documentation in utils/process/executor.hpp for details on
/// the expected workflow of these classes.
#if !defined(ENGINE_SCHEDULER_HPP)
#define ENGINE_SCHEDULER_HPP
#include "engine/scheduler_fwd.hpp"
#include <set>
#include <string>
#include "model/context_fwd.hpp"
#include "model/metadata_fwd.hpp"
#include "model/test_case_fwd.hpp"
#include "model/test_program.hpp"
#include "model/test_result_fwd.hpp"
#include "utils/config/tree_fwd.hpp"
#include "utils/datetime_fwd.hpp"
#include "utils/defs.hpp"
#include "utils/fs/path_fwd.hpp"
#include "utils/optional.hpp"
#include "utils/process/executor_fwd.hpp"
#include "utils/process/status_fwd.hpp"
#include "utils/shared_ptr.hpp"
namespace engine {
namespace scheduler {
/// Abstract interface of a test program scheduler interface.
///
/// This interface defines the test program-specific operations that need to be
/// invoked at different points during the execution of a given test case. The
/// scheduler internally instantiates one of these for every test case.
class interface {
public:
/// Destructor.
virtual ~interface() {}
/// Executes a test program's list operation.
///
/// This method is intended to be called within a subprocess and is expected
/// to terminate execution either by exec(2)ing the test program or by
/// exiting with a failure.
///
/// \param test_program The test program to execute.
/// \param vars User-provided variables to pass to the test program.
virtual void exec_list(const model::test_program& test_program,
const utils::config::properties_map& vars)
const UTILS_NORETURN = 0;
/// Computes the test cases list of a test program.
///
/// \param status The termination status of the subprocess used to execute
/// the exec_test() method or none if the test timed out.
/// \param stdout_path Path to the file containing the stdout of the test.
/// \param stderr_path Path to the file containing the stderr of the test.
///
/// \return A list of test cases.
virtual model::test_cases_map parse_list(
const utils::optional< utils::process::status >& status,
const utils::fs::path& stdout_path,
const utils::fs::path& stderr_path) const = 0;
/// Executes a test case of the test program.
///
/// This method is intended to be called within a subprocess and is expected
/// to terminate execution either by exec(2)ing the test program or by
/// exiting with a failure.
///
/// \param test_program The test program to execute.
/// \param test_case_name Name of the test case to invoke.
/// \param vars User-provided variables to pass to the test program.
/// \param control_directory Directory where the interface may place control
/// files.
virtual void exec_test(const model::test_program& test_program,
const std::string& test_case_name,
const utils::config::properties_map& vars,
const utils::fs::path& control_directory)
const UTILS_NORETURN = 0;
/// Executes a test cleanup routine of the test program.
///
/// This method is intended to be called within a subprocess and is expected
/// to terminate execution either by exec(2)ing the test program or by
/// exiting with a failure.
///
/// \param test_program The test program to execute.
/// \param test_case_name Name of the test case to invoke.
/// \param vars User-provided variables to pass to the test program.
/// \param control_directory Directory where the interface may place control
/// files.
virtual void exec_cleanup(const model::test_program& test_program,
const std::string& test_case_name,
const utils::config::properties_map& vars,
const utils::fs::path& control_directory)
const UTILS_NORETURN;
/// Computes the result of a test case based on its termination status.
///
/// \param status The termination status of the subprocess used to execute
/// the exec_test() method or none if the test timed out.
/// \param control_directory Directory where the interface may have placed
/// control files.
/// \param stdout_path Path to the file containing the stdout of the test.
/// \param stderr_path Path to the file containing the stderr of the test.
///
/// \return A test result.
virtual model::test_result compute_result(
const utils::optional< utils::process::status >& status,
const utils::fs::path& control_directory,
const utils::fs::path& stdout_path,
const utils::fs::path& stderr_path) const = 0;
};
/// Implementation of a test program with lazy loading of test cases.
class lazy_test_program : public model::test_program {
struct impl;
/// Pointer to the shared internal implementation.
std::shared_ptr< impl > _pimpl;
public:
lazy_test_program(const std::string&, const utils::fs::path&,
const utils::fs::path&, const std::string&,
const model::metadata&,
const utils::config::tree&,
scheduler_handle&);
const model::test_cases_map& test_cases(void) const;
};
/// Base type containing the results of the execution of a subprocess.
class result_handle {
protected:
struct bimpl;
private:
/// Pointer to internal implementation of the base type.
std::shared_ptr< bimpl > _pbimpl;
protected:
friend class scheduler_handle;
result_handle(std::shared_ptr< bimpl >);
public:
virtual ~result_handle(void) = 0;
void cleanup(void);
int original_pid(void) const;
const utils::datetime::timestamp& start_time() const;
const utils::datetime::timestamp& end_time() const;
utils::fs::path work_directory(void) const;
const utils::fs::path& stdout_file(void) const;
const utils::fs::path& stderr_file(void) const;
};
/// Container for all test termination data and accessor to cleanup operations.
class test_result_handle : public result_handle {
struct impl;
/// Pointer to internal implementation.
std::shared_ptr< impl > _pimpl;
friend class scheduler_handle;
test_result_handle(std::shared_ptr< bimpl >, std::shared_ptr< impl >);
public:
~test_result_handle(void);
const model::test_program_ptr test_program(void) const;
const std::string& test_case_name(void) const;
const model::test_result& test_result(void) const;
};
/// Stateful interface to the multiprogrammed execution of tests.
class scheduler_handle {
struct impl;
/// Pointer to internal implementation.
std::shared_ptr< impl > _pimpl;
friend scheduler_handle setup(void);
scheduler_handle(void);
public:
~scheduler_handle(void);
const utils::fs::path& root_work_directory(void) const;
void cleanup(void);
model::test_cases_map list_tests(const model::test_program*,
const utils::config::tree&);
exec_handle spawn_test(const model::test_program_ptr,
const std::string&,
const utils::config::tree&);
result_handle_ptr wait_any(void);
result_handle_ptr debug_test(const model::test_program_ptr,
const std::string&,
const utils::config::tree&,
const utils::fs::path&,
const utils::fs::path&);
void check_interrupt(void) const;
};
extern utils::datetime::delta cleanup_timeout;
extern utils::datetime::delta list_timeout;
void ensure_valid_interface(const std::string&);
void register_interface(const std::string&, const std::shared_ptr< interface >);
std::set< std::string > registered_interface_names(void);
scheduler_handle setup(void);
model::context current_context(void);
utils::config::properties_map generate_config(const utils::config::tree&,
const std::string&);
} // namespace scheduler
} // namespace engine
#endif // !defined(ENGINE_SCHEDULER_HPP)