dfhack/library/include/DebugManager.h

133 lines
4.4 KiB
C

/**
Copyright © 2018 Pauli <suokkos@gmail.com>
This software is provided 'as-is', without any express or implied
warranty. In no event will the authors be held liable for any
damages arising from the use of this software.
Permission is granted to anyone to use this software for any
purpose, including commercial applications, and to alter it and
redistribute it freely, subject to the following restrictions:
1. The origin of this software must not be misrepresented; you must
not claim that you wrote the original software. If you use this
software in a product, an acknowledgment in the product
documentation would be appreciated but is not required.
2. Altered source versions must be plainly marked as such, and
must not be misrepresented as being the original software.
3. This notice may not be removed or altered from any source
distribution.
*/
#pragma once
#include "Export.h"
#include "Signal.hpp"
#include <mutex>
#include <vector>
namespace DFHack {
/*! \file DebugManager.h
* Expose an simple interface to runtime debug output filtering. The management
* interface is separated from output interface because output is required in
* many places while management is expected to be required only in a few places.
*/
class DebugCategory;
/*!
* \brief Container holding all registered runtime debug categories
* Singleton DebugManager is a minor extension to std::vector that allows signal
* callbacks to be attached from plotinfo code that manages.
*
* To avoid parallel plugin unload causing issues access to DebugManager must be
* protected by mutex. The access mutex will be taken when
* DFHack::DebugCategory::~DebugCategory performs unregister calls to
* DFHack::DebugManager. The mutex will protect from memory disappearing while
* plotinfo code is accessing or changing the runtime state.
*
* Signal emitting happens from a locked contexts. Taking the
* DFHack::DebugManager::access_mutex_ in a signal callback will results to a
* deadlock.
*
* The interface is extremely simple but enough to implement persistent filter
* states and runtime configuration code in a plugin.
*/
class DFHACK_EXPORT DebugManager : public std::vector<DebugCategory*> {
public:
friend class DebugRegisterBase;
//! access_mutex_ protects all readers and writers to DFHack::DebugManager
std::mutex access_mutex_;
//! Different signals that all will be routed to
//! DebugManager::categorySignal
enum signalType {
CAT_ADD,
CAT_REMOVE,
CAT_MODIFIED,
};
//! Log message header configuration, controlled via the debug plugin
struct HeaderConfig {
bool timestamp = false; // Hour, minute, and seconds
bool timestamp_ms = false; // only used if timestamp == true
bool thread_id = false;
bool plugin = false;
bool category = false;
};
//! type to help access signal features like Connection and BlockGuard
using categorySignal_t = Signal<void (signalType, DebugCategory&)>;
/*!
* Signal object where callbacks can be connected. Connecting to a class
* method can use a lambda wrapper to the capture object pointer and correctly
* call required method.
*
* Signal is internally serialized allowing multiple threads call it
* freely.
*/
categorySignal_t categorySignal;
//! Get the singleton object
static DebugManager& getInstance() {
static DebugManager instance;
return instance;
}
// don't bother to protect these with mutexes. we don't want to pay the
// performance cost of locking on every log message, and the consequences
// of race conditions are minimal.
const HeaderConfig & getHeaderConfig() const {
return headerConfig;
}
void setHeaderConfig(const HeaderConfig &config) {
headerConfig = config;
}
//! Prevent copies
DebugManager(const DebugManager&) = delete;
//! Prevent copies
DebugManager(DebugManager&&) = delete;
//! Prevent copies
DebugManager& operator=(DebugManager) = delete;
//! Prevent copies
DebugManager& operator=(DebugManager&&) = delete;
protected:
DebugManager() = default;
HeaderConfig headerConfig;
//! Helper for automatic category registering and signaling
void registerCategory(DebugCategory &);
//! Helper for automatic category unregistering and signaling
void unregisterCategory(DebugCategory &);
private:
};
}