CYB::Engine::Logger Class Reference

The threaded, queued engine logger. More...

#include <CYBLogger.hpp>

Inheritance diagram for CYB::Engine::Logger:

Collaboration diagram for CYB::Engine::Logger:

Classes
struct	LogEntry
	Log entries to be inserted into the queue. More...

Public Member Functions
	Logger (API::Logger &AEmergencyLogger)
	Initializes and starts the Logger. Changes the current Context. May block for one second if the preferred file name is taken in order to generate a new one. More...
	~Logger ()
	Shutdown the Logger and empty the queue.
void	Pause (void) noexcept
	Put the logging thread to sleep. More...
void	Resume (void) noexcept
	Wake the logging thread. More...
void	Log (const API::String::CStyle &AMessage, const Level ALevel) finaloverride
	Log a message. Will be written to a text file on the Path returned by CurrentLog. More...
void	Flush (void) const noexceptfinaloverride
	Delays execution until all pending logs from the current thread have been written to the output. More...
const API::String::CStyle &	CurrentLog (void) const noexceptfinaloverride
	Retrieve the string representation of the Path of the File the Logger is currently writing to. More...
void	SetDebugLogging (const bool AEnable) noexceptfinaloverride
	Enable/Disable filtering of Level::DEV logs. More...

Private Member Functions
void	EmptyQueue (void)
	Empty FQueue and write it into FFile. More...
API::Threadable &	SelfAsThreadable (void) noexcept
	Returns the current object as a Threadable reference. Used to get around some weird VS construction issues. More...
void	BeginThreadedOperation (void) override
	Writer thread. Runs in a loop until CancelThreadedOperation is called. More...
void	CancelThreadedOperation (void) override
	Stops the writer thread. Does not guarantee an empty queue. More...

Static Private Member Functions
static API::String::Dynamic	TimeString (const int AHour, const int AMinute, const int ASecond, const bool AColons)
	Retrieve a string of the given time. More...
static API::String::Dynamic	TimeString (const bool AColons)
	Retrieve a string of the current time. More...
static API::String::Dynamic	FormatLogMessage (const API::String::CStyle &AMessage, const Level ALevel)
	Prepend the level and time to a log message. More...
static Platform::System::File	OpenFileImpl (const Platform::System::Path &ABasePath)
	Prepares the logging File for writing. May block for one second if the preferred filename is taken in order to generate a new one. More...
static Platform::System::File	OpenFile (void)
	Prepares the logging File for writing. May block for one second if the preferred filename is taken in order to generate a new one. More...
static void	LogShutdownForEntry (API::UniquePointer< LogEntry > &&AEntry, API::Logger &AEmergency) noexcept
	Takes a LogEntry Queue and logs it out to the current given emergency logger. More...

Private Attributes
Memory::Heap	FHeap
	The isolated Heap.
Context	FContext
	The Context to be used when calling the Logger.
Platform::System::File	FFile
	The File being written to.
Platform::System::Mutex	FQueueLock
	The lock used to acquire access to FQueue.
Platform::System::Mutex	FFileLock
	The lock used to acquire access to FFile.
API::UniquePointer< LogEntry >	FQueueHead
	The message queue head.
LogEntry *	FQueueTail
	The message queue tail.
API::Interop::Object < Platform::System::Thread >	FThread
	The thread used for writing to the log file.
std::atomic_bool	FCancelled
	Cancel flag for FThread.
std::atomic_bool	FDevLog
	Flag for enabling/disabling DEV logs.
std::atomic_bool	FPaused
	Flag for sleeping the logging thread.

Additional Inherited Members
Public Types inherited from CYB::API::Logger
enum	Level : byte { Level::DEV, Level::INFO, Level::WARN, Level::ERR }
	The severity of the log. More...

Detailed Description

The threaded, queued engine logger.

Definition at line 7 of file CYBLogger.hpp.

Constructor & Destructor Documentation

CYB::Engine::Logger::Logger

(

API::Logger &

AEmergencyLogger

)

Initializes and starts the Logger. Changes the current Context. May block for one second if the preferred file name is taken in order to generate a new one.

Parameters

AEmergencyLogger

The Logger to write errors to if this one fails

Thread Safety

This function requires no thread safety

Exceptions

CYB::Exception::SystemData	Error code: CYB::Exception::SystemData::STREAM_NOT_WRITABLE. Thrown if the log File could not be opened
CYB::Exception::SystemData	Error code: CYB::Exception::SystemData::SYSTEM_PATH_RETRIEVAL_FAILURE. Thrown if the temporary Path could not be retrieved
CYB::Exception::SystemData	Error code: CYB::Exception::SystemData::STREAM_NOT_READABLE. Thrown if Path errors occured while setting up the file
CYB::Exception::SystemData	Error code: CYB::Exception::SystemData::STREAM_NOT_WRITABLE. Thrown if the log File could not be written to
CYB::Exception::SystemData	Error code: CYB::Exception::SystemData::PATH_TOO_LONG. Thrown if the new Path would exceed the limitation
CYB::Exception::SystemData	Error code: CYB::Exception::SystemData::PATH_LOST. Thrown if Path errors occured while setting up the file
CYB::Exception::SystemData	Error code: CYB::Exception::SystemData::MUTEX_INITIALIZATION_FAILURE. Thrown if one of the Mutexes could not be initialized
CYB::Exception::Internal	Error code: CYB::Exception::Internal::MEMORY_RESERVATION_FAILURE. Thrown if the Heap memory could not be reserved
CYB::Exception::Internal	Error code: CYB::Exception::Internal::MEMORY_COMMITAL_FAILURE. Thrown if the Heap memory could not be committed Theoretically this could throw CYB::Exception::SystemData::HEAP_ALLOCATION_FAILURE on some string allocations, but given the initial empty Heap this is practiacally impossible

Definition at line 66 of file CYBLogger.cpp.

                                                   :
    FHeap(Parameters::LOGGER_HEAP_INITIAL_COMMIT_SIZE),
    FContext(FHeap, AEmergencyLogger, true),
    FFile(OpenFile()),
    FThread(nullptr),
    FCancelled(false),
    FDevLog(
#ifdef DEBUG
        true
#else
        false
#endif
    )
{
    FQueueHead.reset(static_cast<Allocator&>(Context::GetContext().FAllocator).RawObject<LogEntry>());
    FQueueHead->FLevel = Level::INFO;
    FQueueHead->FMessage = FormatLogMessage(API::String::Static(u8"CyberEngineMkIII logger started..."), Level::INFO);

    FQueueTail = FQueueHead.get();

    //Flush this message in case it all goes downhill from here
    EmptyQueue();

    FThread = FContext.FAllocator.ConstructObject<Platform::System::Thread, API::Interop::NullConstructor>(SelfAsThreadable());
}

Here is the call graph for this function:

Member Function Documentation

void CYB::Engine::Logger::BeginThreadedOperation ( void  )

overrideprivatevirtual

Writer thread. Runs in a loop until CancelThreadedOperation is called.

Thread Safety

This function requires no thread safety

Exceptions

CYB::Exception::SystemData

Error code: CYB::Exception::SystemData::STREAM_NOT_WRITABLE. Thrown if the log File could not be written to

Implements CYB::API::Threadable.

Definition at line 152 of file CYBLogger.cpp.

                                                 {
    PushContext Push(FContext);
    while (!FCancelled.load(std::memory_order_relaxed)) {
        if(!FPaused.load(std::memory_order_acquire))
            EmptyQueue();
        Platform::System::Thread::Sleep(1);
    }
}

Here is the call graph for this function:

void CYB::Engine::Logger::CancelThreadedOperation ( void  )

overrideprivatevirtual

Stops the writer thread. Does not guarantee an empty queue.

Thread Safety

This function requires no thread safety

Implements CYB::API::Threadable.

Definition at line 161 of file CYBLogger.cpp.

                                                  {
    FCancelled.store(true, std::memory_order_relaxed);
}

const CYB::API::String::CStyle & CYB::Engine::Logger::CurrentLog ( void  ) const

finaloverridevirtualnoexcept

Retrieve the string representation of the Path of the File the Logger is currently writing to.

Returns

The string representation of the Path of the File the Logger is currently writing to

Thread Safety

This function requires no thread safety

Implements CYB::API::Logger.

Definition at line 243 of file CYBLogger.cpp.

                                                                         {
    return FFile.GetPath()();
}

void CYB::Engine::Logger::EmptyQueue ( void  )

private

Empty FQueue and write it into FFile.

Thread Safety

This function requires no thread safety

Exceptions

CYB::Exception::SystemData

Error code: CYB::Exception::SystemData::STREAM_NOT_WRITABLE. Thrown if the log File could not be written to

Definition at line 112 of file CYBLogger.cpp.

                                     {
    API::UniquePointer<LogEntry> Queue, NextNode;
    {
        API::LockGuard Lock(FQueueLock);
        Queue = std::move(FQueueHead);
        FQueueTail = nullptr;
        FFileLock.Lock();
    }

    API::LockGuard FLock(FFileLock, true);

    for (; Queue.get() != nullptr; Queue = std::move(NextNode)) {
        NextNode = std::move(Queue->FNext);
        const auto Len(static_cast<unsigned int>(Queue->FMessage.RawLength()));
        auto Written(0ULL);
        do {
            const auto CurrentWrite(FFile.Write(Queue->FMessage.CString() + Written, Len - Written));
            if (CurrentWrite == 0) {
                //CurrentContext will most certainly be FContext at this point
                //but just in case we add some weird behaviour overrides in the future....
                auto& EmergencyLogger(Context::GetContext().FLogger);
                EmergencyLogger.SetDebugLogging(true);
                EmergencyLogger.Log(API::String::Static(u8"Failed to write to primary log. Message follows:"), Level::ERR);
                EmergencyLogger.Log(Queue->FMessage, Queue->FLevel);
                if (NextNode != nullptr) {
                    EmergencyLogger.Log(API::String::Static(u8"Remaining entries follow:"), Level::INFO);
                    LogShutdownForEntry(std::move(NextNode), EmergencyLogger);
                }
                throw CYB::Exception::SystemData(CYB::Exception::SystemData::STREAM_NOT_WRITABLE);
            }
            Written += CurrentWrite;
        } while (Written < Len);
        API::Assert::Equal<unsigned long long>(Written, Len);
    }
}

Here is the call graph for this function:

Here is the caller graph for this function:

void CYB::Engine::Logger::Flush ( void  ) const

finaloverridevirtualnoexcept

Delays execution until all pending logs from the current thread have been written to the output.

Thread Safety

This function requires no thread safety

Attention

This does not call Resume and may result in a deadlock if called while paused

Implements CYB::API::Logger.

Definition at line 232 of file CYBLogger.cpp.

                                               {
    do {
        {
            API::LockGuard QueueLock(FQueueLock), FileLock(FFileLock);
            if (FQueueHead == nullptr)
                break;
        }
        Platform::System::Thread::Sleep(1);
    } while (true);
}

Here is the call graph for this function:

CYB::API::String::Dynamic CYB::Engine::Logger::FormatLogMessage ( const API::String::CStyle &  AMessage, const Level  ALevel  )

staticprivate

Prepend the level and time to a log message.

Parameters

AMessage	The message to format
ALevel	The Level of AMessage

Returns

AMessage prepended with the current time and Level string

Thread Safety

This function requires no thread safety

Exceptions

CYB::Exception::SystemData	Error code: CYB::Exception::SystemData::HEAP_ALLOCATION_FAILURE. Thrown if the current heap runs out of memory
CYB::Exception::Violation	Error code: CYB::Exception::Violation::INVALID_ENUM. Thrown if the ALevel is invalid

Definition at line 165 of file CYBLogger.cpp.

                                                                                                         {
    const char* LevelString;
    switch (ALevel) {
    case Level::DEV:
        LevelString = u8"Debug: ";
        break;
    case Level::INFO:
        LevelString = u8"Info: ";
        break;
    case Level::WARN:
        LevelString = u8"Warning: ";
        break;
    case Level::ERR:
        LevelString = u8"ERROR: ";
        break;
    default:
        throw CYB::Exception::Violation(CYB::Exception::Violation::INVALID_ENUM);
    }

    const auto ThreadID(Core::GetCore().ThreadID());
    API::String::Dynamic Tabs(":");
    if (ThreadID > 1) {
        const API::String::Static Tab(u8"\t");
        for (auto I(1ULL); I < ThreadID; ++I)
            Tabs += Tab;    //This is pretty performant considering the allocater works in chunks
    }
    else
        Tabs += API::String::Static(" ");

    return TimeString(true) + Tabs + API::String::Static(LevelString) + AMessage;
}

Here is the call graph for this function:

Here is the caller graph for this function:

void CYB::Engine::Logger::Log ( const API::String::CStyle &  AMessage, const Level  ALevel  )

finaloverridevirtual

Log a message. Will be written to a text file on the Path returned by CurrentLog.

Parameters

AMessage	The message to log
ALevel	The Level of the message

Thread Safety

This function requires no thread safety

Exceptions

CYB::Exception::Violation

Error code: CYB::Exception::Violation::INVALID_ENUM. Thrown if the ALevel is invalid In the near impossible case that the isolated Heap the Logger uses runs out of memory, this function will block and flush the write queue to free space This function may silently fail in the case that the log cannot be written to

Implements CYB::API::Logger.

Definition at line 197 of file CYBLogger.cpp.

                                                                             {
    if (ALevel != Level::DEV || FDevLog.load(std::memory_order_relaxed)) {
        PushContext Push(FContext); //Use ourselves for allocation
        bool CritFail(false);
        for (auto I(0U); I < (Parameters::LOGGER_HEAP_RETRY_COUNT + 1) && !CritFail; ++I) {
            try {
                API::UniquePointer<LogEntry> Entry(static_cast<Allocator&>(Context::GetContext().FAllocator).RawObject<LogEntry>());
                Entry->FMessage = API::String::Dynamic(u8"\n") + FormatLogMessage(AMessage, ALevel);
                Entry->FLevel = ALevel;
                auto Tmp(Entry.get());

                API::LockGuard Lock(FQueueLock);
                if (FQueueTail != nullptr)
                    FQueueTail->FNext = std::move(Entry);
                else
                    FQueueHead = std::move(Entry);
                FQueueTail = Tmp;
                break;
            }
            catch (CYB::Exception::SystemData& AException) {
                API::Assert::Equal<unsigned int>(AException.FErrorCode, CYB::Exception::SystemData::HEAP_ALLOCATION_FAILURE);
                try {
                    //Empty the queue, free the memory, and try again
                    EmptyQueue();
                }
                catch (CYB::Exception::SystemData& AInnerException) {
                    API::Assert::Equal<unsigned int>(AInnerException.FErrorCode, CYB::Exception::SystemData::STREAM_NOT_WRITABLE);
                    //Now give up
                    CritFail = true;
                }
            }
        }
    }
}

Here is the call graph for this function:

Here is the caller graph for this function:

void CYB::Engine::Logger::LogShutdownForEntry ( API::UniquePointer< LogEntry > &&  AEntry, API::Logger &  AEmergency  )

staticprivatenoexcept

Takes a LogEntry Queue and logs it out to the current given emergency logger.

Parameters

AEntry	An xvalue of a LogEntry. All its contents will be logged and deleted
AEmergency	the current emergency logger

Thread Safety

This function requires no thread safety

Definition at line 101 of file CYBLogger.cpp.

                                                                                                             {
    //Emergency log the message
    auto& Message(AEntry->FMessage);
    const auto ByteIndex(Message.IndexOfByte(':', 3) + 1);  //+1 to comp for the space
    API::Assert::LessThan(0, ByteIndex);
    API::Assert::LessThan(ByteIndex, Message.RawLength());
    AEmergency.Log(API::String::Static(Message.CString() + ByteIndex), AEntry->FLevel);
    if (AEntry->FNext != nullptr)
        LogShutdownForEntry(std::move(AEntry->FNext), AEmergency);
}

Here is the call graph for this function:

CYB::Platform::System::File CYB::Engine::Logger::OpenFile ( void  )

staticprivate

Prepares the logging File for writing. May block for one second if the preferred filename is taken in order to generate a new one.

Returns

The File to be used for logging

Thread Safety

This function requires no thread safety

Exceptions

CYB::Exception::SystemData	Error code: CYB::Exception::SystemData::STREAM_NOT_WRITABLE. Thrown if the log File could not be opened
CYB::Exception::SystemData	Error code: CYB::Exception::SystemData::SYSTEM_PATH_RETRIEVAL_FAILURE. Thrown if the temporary Path could not be retrieved
CYB::Exception::SystemData	Error code: CYB::Exception::SystemData::STREAM_NOT_READABLE. Thrown if Path errors occured while setting up the file
CYB::Exception::SystemData	Error code: CYB::Exception::SystemData::PATH_TOO_LONG. Thrown if the new Path would exceed the limitation
CYB::Exception::SystemData	Error code: CYB::Exception::SystemData::PATH_LOST. Thrown if Path errors occured while setting up the file Theoretically this could throw CYB::Exception::SystemData::HEAP_ALLOCATION_FAILURE on some string allocations, but given the initial empty Heap this is practically impossible

Definition at line 60 of file CYBLogger.cpp.

                                                    {
    //All allocation is done using the Logger's Allocator
    Platform::System::Path ThePath(API::Path::SystemPath::TEMPORARY);
    return OpenFileImpl(ThePath);
}

CYB::Platform::System::File CYB::Engine::Logger::OpenFileImpl ( const Platform::System::Path &  ABasePath )

staticprivate

Prepares the logging File for writing. May block for one second if the preferred filename is taken in order to generate a new one.

Parameters

ABasePath

A Path to the directory to log in

Returns

The File to be used for logging

Thread Safety

This function requires no thread safety

Exceptions

CYB::Exception::SystemData	Error code: CYB::Exception::SystemData::STREAM_NOT_WRITABLE. Thrown if the log File could not be opened
CYB::Exception::SystemData	Error code: CYB::Exception::SystemData::SYSTEM_PATH_RETRIEVAL_FAILURE. Thrown if the temporary Path could not be retrieved
CYB::Exception::SystemData	Error code: CYB::Exception::SystemData::STREAM_NOT_READABLE. Thrown if Path errors occured while setting up the file
CYB::Exception::SystemData	Error code: CYB::Exception::SystemData::PATH_TOO_LONG. Thrown if the new Path would exceed the limitation
CYB::Exception::SystemData	Error code: CYB::Exception::SystemData::PATH_LOST. Thrown if Path errors occured while setting up the file Theoretically this could throw CYB::Exception::SystemData::HEAP_ALLOCATION_FAILURE on some string allocations, but given the initial empty Heap this is practically impossible

Definition at line 30 of file CYBLogger.cpp.

                                                                                          {
    try {

        auto Time(time(0));   // get time now
        auto Now(localtime(&Time));

        const int Year(Now->tm_year + 1900), Month(Now->tm_mon + 1), Day(Now->tm_mday), Hour(Now->tm_hour), Min(Now->tm_min), Sec(Now->tm_sec);

        char Buffer[50];
        memset(Buffer, 0, 50);
        const auto Length(sprintf(Buffer, u8"Engine Log %d-%d-%d %s.txt", Year, Month, Day, TimeString(Hour, Min, Sec, false).CString()));

        API::Assert::LessThan(-1, Length);
        API::Assert::LessThan(Length, 50);

        API::String::Static AsStatic(Buffer);
        API::String::UTF8 Formatted(AsStatic);

        auto LogPath(ABaseLogPath);
        LogPath.Append(std::move(Formatted), false, false);

        return Platform::System::File(std::move(LogPath), API::File::Mode::WRITE, API::File::Method::CREATE);
    }
    catch (CYB::Exception::SystemData& AException) {
        if (AException.FErrorCode != CYB::Exception::SystemData::FILE_EXISTS)
            throw;
    }
    Platform::System::Thread::Sleep(1000);
    return OpenFileImpl(ABaseLogPath);
}

Here is the call graph for this function:

void CYB::Engine::Logger::Pause ( void  )

noexcept

Put the logging thread to sleep.

Thread Safety

This function requires no thread safety

Definition at line 251 of file CYBLogger.cpp.

                                         {
    API::LockGuard QueueLock(FQueueLock), FileLock(FFileLock);
    FPaused.store(true, std::memory_order_relaxed);
}

void CYB::Engine::Logger::Resume ( void  )

noexcept

Wake the logging thread.

Thread Safety

This function requires no thread safety

Definition at line 256 of file CYBLogger.cpp.

                                          {
    FPaused.store(false, std::memory_order_relaxed);
}

CYB::API::Threadable & CYB::Engine::Logger::SelfAsThreadable ( void  )

privatenoexcept

Returns the current object as a Threadable reference. Used to get around some weird VS construction issues.

Returns

*this;

Thread Safety

This function requires no thread safety

Definition at line 148 of file CYBLogger.cpp.

                                                                 {
    return *this;
}

Here is the caller graph for this function:

void CYB::Engine::Logger::SetDebugLogging ( const bool  AEnable )

finaloverridevirtualnoexcept

Enable/Disable filtering of Level::DEV logs.

Parameters

AEnable

Enables DEV logs if true, disables them otherwise

Thread Safety

This function requires no thread safety

Implements CYB::API::Logger.

Definition at line 247 of file CYBLogger.cpp.

                                                                 {
    FDevLog.store(AEnable, std::memory_order_release);
}

CYB::API::String::Dynamic CYB::Engine::Logger::TimeString ( const int  AHour, const int  AMinute, const int  ASecond, const bool  AColons  )

staticprivate

Retrieve a string of the given time.

Parameters

AHour	The hour to display
AMinute	The minute to display
ASecond	The second to display
AColons	If true, print with brackets and colons. Otherwise use dashes

Returns

An API::String::Dynamic with the given time in the format "[HH:MM:SS]" or "HH-MM-SS" depending on AColons

Thread Safety

This function requires no thread safety

Exceptions

CYB::Exception::SystemData

Error code: CYB::Exception::SystemData::HEAP_ALLOCATION_FAILURE. Thrown if the current heap runs out of memory

Definition at line 8 of file CYBLogger.cpp.

                                                                                                                         {
    char Buffer[50];
    memset(Buffer, 0, 50);
    int Length;
    if (AColons)
        Length = sprintf(Buffer, u8"[%02d:%02d:%02d]", AHour, AMinute, ASecond);
    else
        Length = sprintf(Buffer, u8"%02d-%02d-%02d", AHour, AMinute, ASecond);

    API::Assert::LessThan(-1, Length);
    API::Assert::LessThan(Length, 50);

    return API::String::Dynamic(API::String::Static(Buffer));
}

Here is the call graph for this function:

CYB::API::String::Dynamic CYB::Engine::Logger::TimeString ( const bool  AColons )

staticprivate

Retrieve a string of the current time.

Parameters

AColons

If true, print with brackets and colons. Otherwise use dashes

Returns

An API::String::Dynamic with the given time in the format "[HH:MM:SS]" or "HH-MM-SS" depending on AColons

Thread Safety

This function requires no thread safety

Exceptions

CYB::Exception::SystemData

Error code: CYB::Exception::SystemData::HEAP_ALLOCATION_FAILURE. Thrown if the current heap runs out of memory

Definition at line 23 of file CYBLogger.cpp.

                                                                  {
    auto Time(time(0));   // get time now
    auto Now(localtime(&Time));
    const auto Hour(Now->tm_hour), Min(Now->tm_min), Sec(Now->tm_sec);
    return TimeString(Hour, Min, Sec, AColons);
}

---

The documentation for this class was generated from the following files:

• Engine/Engine/Core/CYBLogger.hpp
• Engine/Engine/Core/CYBLogger.cpp

---

Generated by   1.8.6