interface.h

Go to the documentation of this file.

// Copyright 2011-2025:
//   GobySoft, LLC (2013-)
//   Massachusetts Institute of Technology (2007-2014)
//   Community contributors (see AUTHORS file)
// File authors:
//   Toby Schneider <toby@gobysoft.org>
//
//
// This file is part of the Goby Underwater Autonomy Project Libraries
// ("The Goby Libraries").
//
// The Goby Libraries are free software: you can redistribute them and/or modify
// them under the terms of the GNU Lesser General Public License as published by
// the Free Software Foundation, either version 2.1 of the License, or
// (at your option) any later version.
//
// The Goby Libraries are distributed in the hope that they will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
// GNU Lesser General Public License for more details.
//
// You should have received a copy of the GNU Lesser General Public License
// along with Goby.  If not, see <http://www.gnu.org/licenses/>.
 
#ifndef GOBY_MIDDLEWARE_APPLICATION_INTERFACE_H
#define GOBY_MIDDLEWARE_APPLICATION_INTERFACE_H
 
#include <chrono>
#include <csignal>
#include <iostream>
#include <sys/types.h>
#include <unistd.h>
 
#include <boost/format.hpp>
 
#include "goby/exception.h"
#include "goby/middleware/application/configurator.h"
#include "goby/middleware/marshalling/detail/dccl_serializer_parser.h"
#include "goby/middleware/protobuf/app_config.pb.h"
#include "goby/time.h"
#include "goby/util/debug_logger.h"
#include "goby/util/geodesy.h"
 
namespace goby
{
template <typename App>
int run(const goby::middleware::ConfiguratorInterface<typename App::ConfigType>& cfgtor);
 
template <typename App,
          typename Configurator = middleware::ProtobufConfigurator<typename App::ConfigType>>
int run(int argc, char* argv[])
{
    return run<App>(Configurator(argc, argv));
}
 
namespace middleware
{
 
namespace julia
{
template <typename App> class ApplicationWrapper;
}
 
template <typename Config> class Application
{
  public:
    Application();
    virtual ~Application()
    {
        goby::glog.is_debug2() && goby::glog << "Application: destructing cleanly" << std::endl;
    }
 
    using ConfigType = Config;
 
  protected:
    virtual void pre_initialize(){};
 
    virtual void initialize(){};
 
    virtual void post_initialize(){};
 
    virtual void run() = 0;
 
    virtual void pre_finalize(){};
 
    virtual void finalize(){};
 
    virtual void post_finalize(){};
 
    void quit(int return_value = 0)
    {
        alive_ = false;
        return_value_ = return_value;
    }
 
    const Config& app_cfg() { return *app_cfg_; }
 
    const util::UTMGeodesy& geodesy()
    {
        if (geodesy_)
            return *geodesy_;
        else
            throw(goby::Exception("No lat_origin and lon_origin defined for requested UTMGeodesy"));
    }
 
    bool has_geodesy() { return geodesy_ ? true : false; }
 
    std::string app_name() { return app3_base_configuration_->name(); }
 
    bool app_alive() { return alive_; }
 
    boost::units::quantity<boost::units::si::frequency>
    choose_loop_freq(boost::units::quantity<boost::units::si::frequency> compiled_loop_freq)
    {
        if (app3_base_configuration_->has_loop_frequency())
            return app3_base_configuration_->loop_frequency_with_units();
        else
            return compiled_loop_freq;
    }
 
  protected:
    void configure_geodesy(goby::util::UTMGeodesy::LatLonPoint datum);
 
  private:
    template <typename App>
    friend int ::goby::run(
        const goby::middleware::ConfiguratorInterface<typename App::ConfigType>&);
 
    template <typename App> friend class goby::middleware::julia::ApplicationWrapper;
 
    // main loop that exits on quit(); returns the desired return value
    int __run();
 
    void run_one() { run(); }
 
    void configure_logger();
    void configure_glog_file();
    void check_rotate_glog_file();
 
  private:
    // sets configuration (before Application construction)
    static std::unique_ptr<Config> app_cfg_;
    static std::unique_ptr<protobuf::AppConfig> app3_base_configuration_;
 
    bool alive_;
    int return_value_;
 
    // static here allows fout_ to live until program exit to log glog output
    static std::unique_ptr<std::ofstream> fout_;
 
    goby::time::SteadyClock::time_point next_log_rotate_time_;
 
    std::unique_ptr<goby::util::UTMGeodesy> geodesy_;
};
} // namespace middleware
 
} // namespace goby
 
template <typename Config>
std::unique_ptr<std::ofstream> goby::middleware::Application<Config>::fout_;
 
template <typename Config> std::unique_ptr<Config> goby::middleware::Application<Config>::app_cfg_;
 
template <typename Config>
std::unique_ptr<goby::middleware::protobuf::AppConfig>
    goby::middleware::Application<Config>::app3_base_configuration_;
 
template <typename Config> goby::middleware::Application<Config>::Application() : alive_(true)
{
    using goby::glog;
 
    configure_logger();
    if (app3_base_configuration_->has_geodesy())
        configure_geodesy({app3_base_configuration_->geodesy().lat_origin_with_units(),
                           app3_base_configuration_->geodesy().lon_origin_with_units()});
 
    if (!app3_base_configuration_->IsInitialized())
        throw(middleware::ConfigException("Invalid base configuration"));
 
    glog.is_debug2() && glog << "Application: constructed with PID: " << getpid() << std::endl;
    glog.is_debug1() && glog << "App name is " << app3_base_configuration_->name() << std::endl;
    glog.is_debug2() && glog << "Configuration is: " << app_cfg_->DebugString() << std::endl;
}
 
template <typename Config> void goby::middleware::Application<Config>::configure_logger()
{
    using goby::glog;
 
    // set up the logger
    glog.set_name(app3_base_configuration_->name());
    glog.add_stream(static_cast<util::logger::Verbosity>(
                        app3_base_configuration_->glog_config().tty_verbosity()),
                    &std::cout);
 
    if (app3_base_configuration_->glog_config().show_gui())
        glog.enable_gui();
 
    if (app3_base_configuration_->glog_config().has_file_log())
        configure_glog_file();
 
    if (app3_base_configuration_->glog_config().show_dccl_log())
        goby::middleware::detail::DCCLSerializerParserHelperBase::setup_dlog();
}
 
template <typename Config> void goby::middleware::Application<Config>::check_rotate_glog_file()
{
    using goby::glog;
    if (app3_base_configuration_->glog_config().has_file_log() &&
        app3_base_configuration_->glog_config().file_log().has_log_rotate_sec() &&
        goby::time::SteadyClock::now() > next_log_rotate_time_)
    {
        glog.remove_stream(fout_.get());
        configure_glog_file();
    }
}
 
template <typename Config> void goby::middleware::Application<Config>::configure_glog_file()
{
    const auto& file_log = app3_base_configuration_->glog_config().file_log();
    std::string file_format_str;
 
    std::string file_name_format = file_log.file_name();
 
    if (!file_log.has_file_name() && file_log.omit().file_timestamp())
        file_name_format = "%2%.txt";
 
    if (file_log.has_file_dir() && !file_log.file_dir().empty())
    {
        auto file_dir = file_log.file_dir();
        if (file_dir.back() != '/')
            file_dir += "/";
        file_format_str = file_dir + file_name_format;
    }
    else
    {
        file_format_str = file_name_format;
    }
 
    boost::format file_format(file_format_str);
 
    if (!file_log.omit().file_timestamp())
    {
        if (file_format_str.find("%1") == std::string::npos)
            glog.is_die() &&
                glog << "file_name string must contain \"%1%\" which is expanded to the current "
                        "application start time (e.g. 20190201T184925), unless omit.file_timestamp "
                        "== true. Erroneous file_name is: "
                     << file_format_str << std::endl;
    }
 
    file_format.exceptions(boost::io::all_error_bits ^
                           (boost::io::too_many_args_bit | boost::io::too_few_args_bit));
 
    std::string file_name =
        (file_format % goby::time::file_str() % app3_base_configuration_->name()).str();
    glog.is_verbose() && glog << "logging output to file: " << file_name << std::endl;
 
    fout_.reset(new std::ofstream(file_name.c_str()));
 
    if (!fout_->is_open())
        glog.is_die() && glog << "cannot write glog output to requested file: " << file_name
                              << std::endl;
 
    if (!file_log.omit().latest_symlink())
    {
        std::string file_symlink =
            (file_format % "latest" % app3_base_configuration_->name()).str();
        remove(file_symlink.c_str());
        int result = symlink(realpath(file_name.c_str(), NULL), file_symlink.c_str());
        if (result != 0)
            glog.is_warn() &&
                glog << "Cannot create symlink to latest file. Continuing onwards anyway"
                     << std::endl;
    }
 
    glog.add_stream(file_log.verbosity(), fout_.get());
 
    if (file_log.has_log_rotate_sec())
        next_log_rotate_time_ =
            goby::time::SteadyClock::now() + std::chrono::seconds(file_log.log_rotate_sec());
}
 
template <typename Config>
void goby::middleware::Application<Config>::configure_geodesy(
    goby::util::UTMGeodesy::LatLonPoint datum)
{
    geodesy_.reset(new goby::util::UTMGeodesy(datum));
}
 
template <typename Config> int goby::middleware::Application<Config>::__run()
{
    // block SIGWINCH (change window size) in all threads
    sigset_t signal_mask;
    sigemptyset(&signal_mask);
    sigaddset(&signal_mask, SIGWINCH);
    pthread_sigmask(SIG_BLOCK, &signal_mask, NULL);
 
    this->pre_initialize();
    this->initialize();
    this->post_initialize();
    // continue to run while we are alive (quit() has not been called)
    while (alive_)
    {
        this->run_one();
        this->check_rotate_glog_file();
    }
    this->pre_finalize();
    this->finalize();
    this->post_finalize();
    return return_value_;
}
 
template <typename App>
int goby::run(const goby::middleware::ConfiguratorInterface<typename App::ConfigType>& cfgtor)
{
    int return_value = 0;
    try
    {
        try
        {
            cfgtor.validate();
        }
        catch (middleware::ConfigException& e)
        {
            cfgtor.handle_config_error(e);
            return 1;
        }
 
        // simply print the configuration and exit
        if (cfgtor.app_configuration().debug_cfg())
        {
            std::cout << cfgtor.str() << std::endl;
            exit(EXIT_SUCCESS);
        }
 
        // set configuration
        App::app_cfg_.reset(new typename App::ConfigType(cfgtor.cfg()));
        App::app3_base_configuration_.reset(
            new goby::middleware::protobuf::AppConfig(cfgtor.app_configuration()));
 
        // set up simulation time
        if (App::app3_base_configuration_->simulation().time().use_sim_time())
        {
            goby::time::SimulatorSettings::using_sim_time = true;
            goby::time::SimulatorSettings::warp_factor =
                App::app3_base_configuration_->simulation().time().warp_factor();
            if (App::app3_base_configuration_->simulation().time().has_reference_microtime())
                goby::time::SimulatorSettings::reference_time =
                    std::chrono::system_clock::time_point(std::chrono::microseconds(
                        App::app3_base_configuration_->simulation().time().reference_microtime()));
        }
 
        // instantiate the application (with the configuration already set)
        App app;
        return_value = app.__run();
    }
    catch (std::exception& e)
    {
        // some other exception
        std::cerr << "Application:: uncaught exception: " << e.what() << std::endl;
        throw;
    }
 
    goby::glog.is_debug2() && goby::glog << "goby::run: exiting cleanly with code: " << return_value
                                         << std::endl;
    return return_value;
}
 
#endif