log.h

Go to the documentation of this file.

/******************************************************************************
 * Copyright 2022 ETC Inc.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *    http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 *******************************************************************************
 * This file is a part of EtcPal. For more information, go to:
 * https://github.com/ETCLabs/EtcPal
 ******************************************************************************/
 
 
#ifndef ETCPAL_CPP_LOG_H_
#define ETCPAL_CPP_LOG_H_
 
#include <array>
#include <cstdarg>
#include <cstdio>
#include <cstring>
#include <memory>
#include <queue>
#include <string>
#include "etcpal/common.h"
#include "etcpal/log.h"
#include "etcpal/cpp/common.h"
#include "etcpal/cpp/mutex.h"
#include "etcpal/cpp/signal.h"
#include "etcpal/cpp/thread.h"
 
namespace etcpal
{
 
class LogTimestamp
{
public:
  LogTimestamp() = default;
  constexpr LogTimestamp(unsigned int year,
                         unsigned int month,
                         unsigned int day,
                         unsigned int hour,
                         unsigned int minute,
                         unsigned int second,
                         unsigned int msec       = 0,
                         int          utc_offset = 0);
 
  bool IsValid() const noexcept;
 
  constexpr const EtcPalLogTimestamp&     get() const noexcept;
  ETCPAL_CONSTEXPR_14 EtcPalLogTimestamp& get() noexcept;
 
  static LogTimestamp Invalid();
 
private:
  EtcPalLogTimestamp timestamp_{};
};
 
constexpr LogTimestamp::LogTimestamp(unsigned int year,
                                     unsigned int month,
                                     unsigned int day,
                                     unsigned int hour,
                                     unsigned int minute,
                                     unsigned int second,
                                     unsigned int msec,
                                     int          utc_offset)
    : timestamp_{year, month, day, hour, minute, second, msec, utc_offset}
{
}
 
inline bool LogTimestamp::IsValid() const noexcept
{
  return etcpal_validate_log_timestamp(&timestamp_);
}
 
constexpr const EtcPalLogTimestamp& LogTimestamp::get() const noexcept
{
  return timestamp_;
}
 
ETCPAL_CONSTEXPR_14_OR_INLINE EtcPalLogTimestamp& LogTimestamp::get() noexcept
{
  return timestamp_;
}
 
inline LogTimestamp LogTimestamp::Invalid()
{
  return LogTimestamp{};
}
 
class LogMessageHandler
{
public:
  virtual LogTimestamp GetLogTimestamp();
 
  virtual void HandleLogMessage(const EtcPalLogStrings& strings) = 0;
};
 
inline LogTimestamp LogMessageHandler::GetLogTimestamp()
{
  return LogTimestamp::Invalid();
}
 
enum class LogDispatchPolicy
{
  kDirect,  
  kQueued   
};
 
class Logger
{
public:
  Logger();
 
  bool Startup(LogMessageHandler& message_handler);
  void Shutdown();
 
  bool CanLog(int pri) const noexcept;
  void Log(int pri, const char* format, ...);
 
  void Debug(const char* format, ...);
  void Info(const char* format, ...);
  void Notice(const char* format, ...);
  void Warning(const char* format, ...);
  void Error(const char* format, ...);
  void Critical(const char* format, ...);
  void Alert(const char* format, ...);
  void Emergency(const char* format, ...);
 
  LogDispatchPolicy      dispatch_policy() const noexcept;
  int                    log_mask() const noexcept;
  int                    log_action() const noexcept;
  int                    syslog_facility() const noexcept;
  const char*            syslog_hostname() const noexcept;
  const char*            syslog_app_name() const noexcept;
  const char*            syslog_procid() const noexcept;
  const EtcPalLogParams& log_params() const noexcept;
 
  Logger& SetDispatchPolicy(LogDispatchPolicy new_policy) noexcept;
  Logger& SetLogMask(int log_mask) noexcept;
  Logger& SetLogAction(int log_action) noexcept;
  Logger& SetSyslogFacility(int facility) noexcept;
  Logger& SetSyslogHostname(const char* hostname) noexcept;
  Logger& SetSyslogHostname(const std::string& hostname) noexcept;
  Logger& SetSyslogAppName(const char* app_name) noexcept;
  Logger& SetSyslogAppName(const std::string& app_name) noexcept;
  Logger& SetSyslogProcId(const char* proc_id) noexcept;
  Logger& SetSyslogProcId(const std::string& proc_id) noexcept;
  Logger& SetSyslogProcId(int proc_id) noexcept;
 
  Logger& SetThreadPriority(unsigned int priority) noexcept;
  Logger& SetThreadStackSize(unsigned int stack_size) noexcept;
  Logger& SetThreadName(const char* name) noexcept;
  Logger& SetThreadName(const std::string& name) noexcept;
  Logger& SetThreadPlatformData(void* platform_data) noexcept;
 
private:
  void LogInternal(int pri, const char* format, std::va_list args);
  void LogThreadRun();
  void EmptyLogQueue();
 
  LogDispatchPolicy dispatch_policy_{LogDispatchPolicy::kQueued};
  EtcPalLogParams   log_params_{};
 
  struct LogMessage
  {
    int                                          pri;
    std::array<char, ETCPAL_RAW_LOG_MSG_MAX_LEN> buf;
  };
 
  // Used when dispatch_policy_ == Queued
  // This implementation will become more elegant with the addition of new queue APIs. This is
  // being tracked with ETCPAL-43 and ETCPAL-46.
  std::queue<LogMessage>          msg_q_;
  std::unique_ptr<etcpal::Signal> signal_;
  std::unique_ptr<etcpal::Signal> stop_signal_;
  std::unique_ptr<etcpal::Mutex>  mutex_;
  etcpal::Thread                  thread_;
  bool                            initialized_{false};
};
 
 
extern "C" inline void LogCallbackFn(void* context, const EtcPalLogStrings* strings)
{
  if (context && strings)
  {
    static_cast<LogMessageHandler*>(context)->HandleLogMessage(*strings);
  }
}
 
extern "C" inline void LogTimestampFn(void* context, EtcPalLogTimestamp* timestamp)
{
  if (context && timestamp)
  {
    *timestamp = static_cast<LogMessageHandler*>(context)->GetLogTimestamp().get();
  }
}
 
 
inline Logger::Logger()
{
  // Default logging parameters
  log_params_.action   = ETCPAL_LOG_CREATE_HUMAN_READABLE;
  log_params_.log_fn   = LogCallbackFn;
  log_params_.log_mask = ETCPAL_LOG_UPTO(ETCPAL_LOG_DEBUG);
  log_params_.time_fn  = LogTimestampFn;
  log_params_.context  = nullptr;
}
 
inline bool Logger::Startup(LogMessageHandler& message_handler)
{
  if (etcpal_init(ETCPAL_FEATURE_LOGGING) != kEtcPalErrOk)
    return false;
 
  if (!etcpal_validate_log_params(&log_params_))
  {
    etcpal_deinit(ETCPAL_FEATURE_LOGGING);
    return false;
  }
 
  signal_      = std::make_unique<etcpal::Signal>();
  stop_signal_ = std::make_unique<etcpal::Signal>();
  mutex_       = std::make_unique<etcpal::Mutex>();
 
  if (!signal_ || !stop_signal_ || !mutex_)
  {
    etcpal_deinit(ETCPAL_FEATURE_LOGGING);
    return false;
  }
 
  log_params_.context = &message_handler;
  initialized_        = true;
 
  if (dispatch_policy_ == LogDispatchPolicy::kDirect)
    return true;
 
  // kQueued
  // Start the log dispatch thread
  if (!thread_.SetName("EtcPalLoggerThread").Start(&Logger::LogThreadRun, this))
  {
    initialized_ = false;
    etcpal_deinit(ETCPAL_FEATURE_LOGGING);
    return false;
  }
  return true;
}
 
inline void Logger::Shutdown()
{
  if (initialized_)
  {
    initialized_ = false;
    stop_signal_->Notify();
    if (dispatch_policy_ == LogDispatchPolicy::kQueued)
    {
      signal_->Notify();
      thread_.Join();
    }
    etcpal_deinit(ETCPAL_FEATURE_LOGGING);
    log_params_.context = nullptr;
  }
}
 
inline bool Logger::CanLog(int pri) const noexcept
{
  return etcpal_can_log(&log_params_, pri);
}
 
inline void Logger::Log(int pri, const char* format, ...)
{
  std::va_list args;
  va_start(args, format);
  LogInternal(pri, format, args);
  va_end(args);
}
 
inline void Logger::Debug(const char* format, ...)
{
  std::va_list args;
  va_start(args, format);
  LogInternal(ETCPAL_LOG_DEBUG, format, args);
  va_end(args);
}
 
inline void Logger::Info(const char* format, ...)
{
  std::va_list args;
  va_start(args, format);
  LogInternal(ETCPAL_LOG_INFO, format, args);
  va_end(args);
}
 
inline void Logger::Notice(const char* format, ...)
{
  std::va_list args;
  va_start(args, format);
  LogInternal(ETCPAL_LOG_NOTICE, format, args);
  va_end(args);
}
 
inline void Logger::Warning(const char* format, ...)
{
  std::va_list args;
  va_start(args, format);
  LogInternal(ETCPAL_LOG_WARNING, format, args);
  va_end(args);
}
 
inline void Logger::Error(const char* format, ...)
{
  std::va_list args;
  va_start(args, format);
  LogInternal(ETCPAL_LOG_ERR, format, args);
  va_end(args);
}
 
inline void Logger::Critical(const char* format, ...)
{
  std::va_list args;
  va_start(args, format);
  LogInternal(ETCPAL_LOG_CRIT, format, args);
  va_end(args);
}
 
inline void Logger::Alert(const char* format, ...)
{
  std::va_list args;
  va_start(args, format);
  LogInternal(ETCPAL_LOG_ALERT, format, args);
  va_end(args);
}
 
inline void Logger::Emergency(const char* format, ...)
{
  std::va_list args;
  va_start(args, format);
  LogInternal(ETCPAL_LOG_EMERG, format, args);
  va_end(args);
}
 
inline LogDispatchPolicy Logger::dispatch_policy() const noexcept
{
  return dispatch_policy_;
}
 
inline int Logger::log_mask() const noexcept
{
  return log_params_.log_mask;
}
 
inline int Logger::log_action() const noexcept
{
  return log_params_.action;
}
 
inline int Logger::syslog_facility() const noexcept
{
  return log_params_.syslog_params.facility;
}
 
inline const char* Logger::syslog_hostname() const noexcept
{
  return log_params_.syslog_params.hostname;
}
 
inline const char* Logger::syslog_app_name() const noexcept
{
  return log_params_.syslog_params.app_name;
}
 
inline const char* Logger::syslog_procid() const noexcept
{
  return log_params_.syslog_params.procid;
}
 
inline const EtcPalLogParams& Logger::log_params() const noexcept
{
  return log_params_;
}
 
inline Logger& Logger::SetDispatchPolicy(LogDispatchPolicy new_policy) noexcept
{
  dispatch_policy_ = new_policy;
  return *this;
}
 
inline Logger& Logger::SetLogMask(int log_mask) noexcept
{
  log_params_.log_mask = log_mask;
  return *this;
}
 
inline Logger& Logger::SetLogAction(int log_action) noexcept
{
  log_params_.action = log_action;
  return *this;
}
 
inline Logger& Logger::SetSyslogFacility(int facility) noexcept
{
  log_params_.syslog_params.facility = facility;
  return *this;
}
 
inline Logger& Logger::SetSyslogHostname(const char* hostname) noexcept
{
  ETCPAL_MSVC_NO_DEP_WRN strncpy(log_params_.syslog_params.hostname, hostname, ETCPAL_LOG_HOSTNAME_MAX_LEN - 1);
  log_params_.syslog_params.hostname[ETCPAL_LOG_HOSTNAME_MAX_LEN - 1] = '\0';
  return *this;
}
 
inline Logger& Logger::SetSyslogHostname(const std::string& hostname) noexcept
{
  SetSyslogHostname(hostname.c_str());
  return *this;
}
 
inline Logger& Logger::SetSyslogAppName(const char* app_name) noexcept
{
  ETCPAL_MSVC_NO_DEP_WRN strncpy(log_params_.syslog_params.app_name, app_name, ETCPAL_LOG_APP_NAME_MAX_LEN - 1);
  log_params_.syslog_params.app_name[ETCPAL_LOG_APP_NAME_MAX_LEN - 1] = '\0';
  return *this;
}
 
inline Logger& Logger::SetSyslogAppName(const std::string& app_name) noexcept
{
  SetSyslogAppName(app_name.c_str());
  return *this;
}
 
inline Logger& Logger::SetSyslogProcId(const char* proc_id) noexcept
{
  ETCPAL_MSVC_NO_DEP_WRN strncpy(log_params_.syslog_params.procid, proc_id, ETCPAL_LOG_PROCID_MAX_LEN - 1);
  log_params_.syslog_params.procid[ETCPAL_LOG_PROCID_MAX_LEN - 1] = '\0';
  return *this;
}
 
inline Logger& Logger::SetSyslogProcId(const std::string& proc_id) noexcept
{
  SetSyslogProcId(proc_id.c_str());
  return *this;
}
 
inline Logger& Logger::SetThreadPriority(unsigned int priority) noexcept
{
  thread_.SetPriority(priority);
  return *this;
}
 
inline Logger& Logger::SetThreadStackSize(unsigned int stack_size) noexcept
{
  thread_.SetStackSize(stack_size);
  return *this;
}
 
inline Logger& Logger::SetThreadName(const char* name) noexcept
{
  thread_.SetName(name);
  return *this;
}
 
inline Logger& Logger::SetThreadName(const std::string& name) noexcept
{
  thread_.SetName(name);
  return *this;
}
 
inline Logger& Logger::SetThreadPlatformData(void* platform_data) noexcept
{
  thread_.SetPlatformData(platform_data);
  return *this;
}
 
inline Logger& Logger::SetSyslogProcId(int proc_id) noexcept
{
  ETCPAL_MSVC_NO_DEP_WRN sprintf(log_params_.syslog_params.procid, "%d", proc_id);
  return *this;
}
 
// Private functions
 
inline void Logger::LogInternal(int pri, const char* format, std::va_list args)
{
  if (initialized_)
  {
    if (dispatch_policy_ == LogDispatchPolicy::kDirect)
    {
      etcpal_vlog(&log_params_, pri, format, args);
    }
    else
    {
      {
        etcpal::MutexGuard lock(*mutex_);
        msg_q_.emplace();
        msg_q_.back().pri = pri;
        vsnprintf(msg_q_.back().buf.data(), ETCPAL_RAW_LOG_MSG_MAX_LEN, format, args);
      }
      signal_->Notify();
    }
  }
}
 
inline void Logger::LogThreadRun()
{
  while (!stop_signal_->TryWait())
  {
    EmptyLogQueue();
    signal_->Wait();
  }
  // Bail the queue one last time on exit
  EmptyLogQueue();
}
 
inline void Logger::EmptyLogQueue()
{
  std::queue<LogMessage> to_log;
  {
    etcpal::MutexGuard lock(*mutex_);
    to_log.swap(msg_q_);
  }
 
  while (!to_log.empty())
  {
    etcpal_log(&log_params_, to_log.front().pri, "%s", to_log.front().buf.data());
    to_log.pop();
  }
}
 
};  // namespace etcpal
 
#endif  // ETCPAL_CPP_LOG_H_