Foundation

Table of Contents

• Dependencies
• Features
  • Classes
  • Macros
  • Type Traits
  • Utilities
• Status
• Description
  • Function
  • Deferred
  • OpaqueObject
  • UniqueHandle
• Blog
• Roadmap
• Statistics

🟩 Primitive types, asserts, compiler macros, Function, Span, Result

SaneCppFoundation.h is a library that provides many fundamental type definitions and types widely used by other libraries.
As this is included and needed by almost every other library, it tries to keep bloat to the bare minimum.
Detailed documentation is in the Foundation topic.

Dependencies

• Dependencies: (none)
• All dependencies: (none)

Features

Classes

Class	Description
SC::Span	View over a contiguous sequence of items (pointer + size in elements).
SC::StringSpan	An read-only view over a string (to avoid including Strings library when parsing is not needed).
SC::StringPath	Pre-sized char array holding enough space to represent a file system path.
SC::Result	An ascii string used as boolean result. SC_TRY macro forwards errors to caller.
SC::Function	Wraps function pointers, member functions and lambdas without ever allocating.
SC::Deferred	Executes a function at end of current scope (in the spirit of Zig defer keyword).
SC::OpaqueObject	Hides implementation details from public headers (static PIMPL).
SC::UniqueHandle	Move only handle that has a special tag value flagging its invalid state.

Macros

• Compiler Macros:

Compiler Macros Preprocessor macros to detect compiler and platform features.

Type Traits

• Type Traits:

Type Traits (EnableIf, AddPointer, etc.)

Utilities

Class	Description
SC::Assert	Functions and macros to assert, exit() or abort() and capture backtraces.
SC::AlignedStorage	A buffer of bytes with given alignment.

Status

🟩 Usable
The library is very simple it it has what is needed so far by the other libraries.

Description

There is an hard rule in the library Principles not to include system and compiler headers in public headers.
Foundation provides all primitive types to be used in headers and classes like SC::UniqueHandle, SC::OpaqueObject, SC::AlignedStorage to encourage static PIMPL in order to hide platform specific implementation details everywhere.

Function

Wraps function pointers, member functions and lambdas without ever allocating.

Template Parameters

FuncType

Type of function to be wrapped (Lambda, free function or pointer to member function)

Note

Size of lambdas or less than LAMBDA_SIZE (currently 2 * sizeof(void*)).
If lambda is bigger than LAMBDA_SIZE the constructor will static assert.

Example:

// A regular class with a member function
struct SomeClass
{
    float memberValue = 2.0;
    int   memberFunc(float a) { return static_cast<int>(a + memberValue); }
};
 
// A Functor with operator ()
struct SomeFunctor
{
    float memberValue = 2.0;
    int   operator()(float a) { return static_cast<int>(a + memberValue); }
};
 
// Free function
int someFunc(float a) { return static_cast<int>(a * 2); }
 
// Class too big to be grabbed by copy
struct BigClass
{
    SC::uint64_t values[4];
};
 
void SC::FunctionTest::functionDocumentationSnippet()
{
    SomeClass someClass;
 
    Function<int(float)> func;
 
    func = &someFunc;                                                // Bind free func
    func.bind<SomeClass, &SomeClass::memberFunc>(someClass);         // Bind member func
    func = [](float a) -> int { return static_cast<int>(a + 1.5); }; // Bind lambda func
    func = SomeFunctor{2.5};                                         // Bind a functor
 
    // If you feel brave enough you can retrieve the bound functor by knowing its type
    SC_ASSERT_RELEASE(func.dynamicCastTo<SomeFunctor>()->memberValue == 2.5f);
 
    // This will static_assert because sizeof(BigClass) is bigger than LAMBDA_SIZE
    // BigClass bigClass;
    // func = [bigClass](float a) -> int { return static_cast<int>(a);};
}

Deferred

Executes a function at end of current scope (in the spirit of Zig defer keyword).

Template Parameters

F	The lambda / function to execute

Example:

        HANDLE processHandle = OpenProcess(PROCESS_QUERY_INFORMATION | PROCESS_DUP_HANDLE, FALSE, processId);
        if (processHandle == nullptr)
        {
            return false;
        }
        auto deferDeleteProcessHandle = SC::MakeDeferred(
            // Function (or lambda) that will be invoked at the end of scope
            [&]
            {
                CloseHandle(processHandle);
                processHandle = nullptr;
            });
        // Use processHandle that will be disposed at end of scope by the Deferred
 
        // ...
        // Deferred can be disarmed, meaning that the dispose function will not be executed
        // deferDeleteProcessHandle.disarm();

OpaqueObject

Hides implementation details from public headers (static PIMPL).

Opaque object avoids the heap allocation that often comes with PIMPL, allowing to hide OS specific details from public headers. User declares size in bytes of a struct in the header but the structure can be defined in an implementation .cpp file. Choosing a size that is too small will generate a static_assert that contains in the error message the minimum size to use. Up to 4 functions will need to be defined to avoid linker errors (construct, destruct, moveConstruct, moveAssign). These functions are meant to be defined in a .cpp file that will know how to construct Object, as it can see its definition.

Template Parameters

Definition

Pass in a custom Definition declaring Sizes and alignment on different platforms

Example:

... in the header file

struct FileSystemWatcher
{
  private:
    struct Internal;
 
    struct InternalDefinition
    {
        static constexpr int Windows = 3 * sizeof(void*);
        static constexpr int Apple   = 42 * sizeof(void*);
        static constexpr int Linux   = sizeof(void*) * 4;
        static constexpr int Default = Linux;
 
        static constexpr size_t Alignment = alignof(void*);
 
        using Object = Internal;
    };
 
  public:
    // Must be public to avoid GCC complaining
    using InternalOpaque = OpaqueObject<InternalDefinition>;
 
  private:
    InternalOpaque internal;
 
    //...

... in .cpp file Declare Internal struct with all platform specific details (requiring OS specific headers).

#include "../../FileSystemWatcher/FileSystemWatcher.h"
#include "../../Foundation/Deferred.h"
#include "FileSystemWatcherThreading.h"
 
#include <CoreServices/CoreServices.h> // FSEvents
 
#include <AvailabilityMacros.h>
#include <TargetConditionals.h>
#if TARGET_OS_IPHONE
// TODO: Figure out another API for ios as this is a private API and it will not be accepted on app store.
#include "FSEventsIOS.h"
#endif
 
struct SC::FileSystemWatcher::Internal
{
    FileSystemWatcher* self          = nullptr;
    CFRunLoopRef       runLoop       = nullptr;
    CFRunLoopSourceRef refreshSignal = nullptr;
    FSEventStreamRef   fsEventStream = nullptr;
    FSWThread          pollingThread;
    Result             signalReturnCode = Result(false);
    FSWEventObject     refreshSignalFinished;
    FSWMutex           mutex;
    EventLoopRunner*   eventLoopRunner = nullptr;
 
    // Used to pass data from thread to async callback
    Notification   notification;
    FolderWatcher* watcher;
    FSWAtomicBool  closing;
 
    //...

Declare only two of the four functions to avoid linker errors.

template <>
void SC::FileSystemWatcher::InternalOpaque::construct(Handle& buffer)
{
    placementNew(buffer.reinterpret_as<Object>());
}
template <>
void SC::FileSystemWatcher::InternalOpaque::destruct(Object& obj)
{
    obj.~Object();
}

UniqueHandle

Move only handle that has a special tag value flagging its invalid state.

Typically used to wrap Operating System specific handles.

Template Parameters

Definition

A struct declaring handle type, release function and invalid handle value.

Example:

... definition in header

 
struct SC_FILE_EXPORT FileDescriptorDefinition
{
    using Handle = int; // fd
    static Result releaseHandle(Handle& handle);
 
    static constexpr Handle Invalid = -1; // invalid fd
};

... derive from it

 
struct SC_FILE_EXPORT FileDescriptor : public UniqueHandle<detail::FileDescriptorDefinition>
{
    using UniqueHandle::UniqueHandle;
 

...declaration in .cpp file

#include <errno.h>      // errno
#include <fcntl.h>      // fcntl
#include <sys/socket.h> // socket/connect/accept
#include <sys/stat.h>   // fstat
#include <sys/un.h>     // sockaddr_un
#include <unistd.h>     // close
 
namespace
{
static SC::TimeMs fileDescriptorPosixTimespecToTimeMs(const timespec& timespecValue)
{
    return SC::TimeMs{static_cast<SC::int64_t>(timespecValue.tv_sec) * 1000 +
                      static_cast<SC::int64_t>(timespecValue.tv_nsec / (1000 * 1000))};
}
 
static SC::FileDescriptorEntryType fileDescriptorPosixEntryTypeFromMode(mode_t mode)
{
    if (S_ISREG(mode))
        return SC::FileDescriptorEntryType::File;
    if (S_ISDIR(mode))
        return SC::FileDescriptorEntryType::Directory;
    if (S_ISLNK(mode))
        return SC::FileDescriptorEntryType::SymbolicLink;
    return SC::FileDescriptorEntryType::Other;
}
 
static SC::Result fillFileDescriptorPosixStat(const struct stat& pathStat, SC::FileDescriptorStat& fileStat)
{
    fileStat               = {};
    fileStat.entryType     = fileDescriptorPosixEntryTypeFromMode(pathStat.st_mode);
    fileStat.fileSize      = static_cast<SC::size_t>(pathStat.st_size);
    fileStat.hardLinkCount = static_cast<SC::size_t>(pathStat.st_nlink);
    fileStat.accessedTime  = fileDescriptorPosixTimespecToTimeMs(
#if __APPLE__
        pathStat.st_atimespec
#else
        pathStat.st_atim
#endif
    );
    fileStat.modifiedTime = fileDescriptorPosixTimespecToTimeMs(
#if __APPLE__
        pathStat.st_mtimespec
#else
        pathStat.st_mtim
#endif
    );
#if __APPLE__
    fileStat.creationTime = fileDescriptorPosixTimespecToTimeMs(pathStat.st_birthtimespec);
#endif
    fileStat.posix.mode          = static_cast<SC::uint32_t>(pathStat.st_mode);
    fileStat.posix.uid           = static_cast<SC::uint32_t>(pathStat.st_uid);
    fileStat.posix.gid           = static_cast<SC::uint32_t>(pathStat.st_gid);
    fileStat.posix.inode         = static_cast<SC::uint64_t>(pathStat.st_ino);
    fileStat.posix.device        = static_cast<SC::uint64_t>(pathStat.st_dev);
    fileStat.posix.specialDevice = static_cast<SC::uint64_t>(pathStat.st_rdev);
    fileStat.posix.blocks        = static_cast<SC::uint64_t>(pathStat.st_blocks);
    fileStat.posix.blockSize     = static_cast<SC::uint64_t>(pathStat.st_blksize);
    return SC::Result(true);
}
} // namespace
 
//-------------------------------------------------------------------------------------------------------
// FileDescriptorDefinition
//-------------------------------------------------------------------------------------------------------
SC::Result SC::detail::FileDescriptorDefinition::releaseHandle(Handle& handle)
{
    if (::close(handle) != 0)
    {
        return Result::Error("FileDescriptorDefinition::releaseHandle - close failed");
    }
    return Result(true);
}

...usage

#include <fcntl.h> // for open
SC::Result SC::FileTest::snippetForUniqueHandle()
{
    StringPath filePath;
    SC_TRY(filePath.assign("someFile.txt"));
 
    const int flags  = O_RDWR | O_CREAT | O_TRUNC; // Open for read/write, create if not exists, truncate if exists
    const int access = S_IRUSR | S_IWUSR | S_IRGRP | S_IROTH; // Read/write for owner, read for group and others
 
    FileDescriptor myDescriptor;
 
    const int nativeFd = ::open(filePath.view().bytesIncludingTerminator(), flags, access);
 
    // Assign the native handle to UniqueHandle (will release the existing one, if any)
    SC_TRY(myDescriptor.assign(nativeFd));
 
    // UniqueHandle can only be moved, but not copied
    FileDescriptor otherDescriptor = move(myDescriptor);
    // FileDescriptor otherDescriptor = myDescriptor; // <- Doesn't compile
 
    // Explicitly close (or it will be automatically released on scope close / destructor)
    SC_TRY(otherDescriptor.close());
 
    // If detach() is called, the handle will be made invalid without releasing it
    otherDescriptor.detach();
 
    // Check handle for validity
    if (otherDescriptor.isValid())
    {
        // ... do something
    }
    return Result(true);
}

Blog

Some relevant blog posts are:

• January 2025 Update
• June 2025 Update
• July 2025 Update

Roadmap

🟦 Complete Features:

• Things will be added as needed

Statistics

Type	Lines Of Code	Comments	Sum
Headers	1136	688	1824
Sources	274	50	324
Sum	1410	738	2148