C++ Classes Reference

This section provides detailed documentation for all C++ classes in the FalconAS HTTP/1.2 server.

Detailed Doxygen UML diagrams can be found here: https://docs.webcodex.de/developer/falconas/doxygen/index.html.

Core Server Classes

Server

The main server class that orchestrates all server operations. Inherits from ResultProcessor, ASProcessHandler, and ClientHandler.

class Server

Public Methods:

Server(): Constructor - Initializes the server instance.

~Server(): Destructor - Cleans up server resources.

void init(): Initializes all server components.

void setupSocket(): Sets up the server listening socket.

void setupPoll(): Sets up polling mechanism for the server socket.

void ServerLoop(): Main server loop that handles incoming connections and processes requests.

void acceptClient(): Accepts new client connections.

void setTerminationHandler(): Sets up signal handler for graceful termination.

static void terminate(int): Static termination handler called on SIGTERM.

void setupSharedMemory(): Sets up shared memory segments for IPC.

void setupFDPassingServer(): Sets up Unix domain socket for file descriptor passing.

void handleFDPassingRequests(): Handles file descriptor passing requests from child processes.

static void addChildPID(pid_t): Registers a child process PID for termination tracking.

static void terminateChildren(): Sends termination signal to all child processes.

Private Members:

string SocketListenAddress: IPv4 address to bind the server socket.

uint SocketListenPort: Port number to listen on.

struct sockaddr_in SocketAddr: Server socket address structure.

struct sockaddr_in ClientSocketAddr: Client socket address structure.

int ServerSocketFD: Server socket file descriptor.

struct pollfd ServerConnFD[1]: Poll file descriptor array for server socket.

void *_SHMStaticFS: Pointer to static filesystem shared memory.

void *_SHMPythonASMeta: Pointer to Python application server metadata shared memory.

void *_SHMPythonASRequests: Pointer to Python AS request payload shared memory.

void *_SHMPythonASResults: Pointer to Python AS result payload shared memory.

int _FDPassingServerFD: File descriptor for Unix domain socket used in FD passing.

static std::vector<pid_t> ChildPIDs: Vector storing all child process IDs for termination management.

Client

Represents a client connection and manages client-specific state.

class Client

Public Methods:

Client(ClientFD_t): Constructor - Creates a client instance with the given file descriptor.

~Client(): Destructor - Cleans up client resources.

ClientRequestNr_t getNextReqNr(): Returns the next request number for this client.

Type Definitions:

typedef uint16_t ClientFD_t: Client file descriptor type.

typedef uint16_t ClientRequestNr_t: Client request number type.

Protected Members:

ClientFD_t _ClientFD: Client socket file descriptor.

Private Members:

ClientRequestNr_t _RequestNr: Current request number for this client.

bool _Error: Error flag indicating if an error occurred.

uint16_t _ErrorID: Error identifier code.

time_t _RequestStartTime: Timestamp when the request started.

time_t _RequestEndTime: Timestamp when the request ended.

time_t _ResponseStartTime: Timestamp when the response started.

time_t _ResponseEndTime: Timestamp when the response ended.

bool _TimeoutReached: Flag indicating if timeout was reached.

ClientHandler

Handles client connections, epoll setup, and data buffering.

class ClientHandler

Type Definitions:

typedef std::shared_ptr<HTTPParser> ClientRef_t: Shared pointer to HTTP parser for client.

typedef pair<uint16_t, const ClientRef_t> ClientMapPair_t: Pair of client FD and client reference.

typedef unordered_map<uint16_t, const ClientRef_t> ClientMap_t: Map of client file descriptors to client references.

typedef struct ClientHandlerSHMPointer_t

Structure holding pointers to shared memory segments:

void* StaticFSPtr - Static filesystem SHM pointer
void* PostASMetaPtr - AS metadata SHM pointer
void* PostASRequestsPtr - AS requests SHM pointer
void* PostASResultsPtr - AS results SHM pointer

Public Methods:

ClientHandler(): Constructor - Initializes client handler and sets up epoll.

~ClientHandler(): Destructor - Cleans up client handler resources.

void addClient(const uint16_t): Adds a new client to the handler with the given file descriptor.

void processClients(): Processes all clients with waiting data using epoll.

void readClientData(const uint16_t): Reads data from the specified client file descriptor.

void setSharedMemPointer(ClientHandlerSHMPointer_t): Sets the shared memory pointers for client handler.

void setClientHandlerConfig(): Configures the client handler settings.

ASRequestHandler &getClientHandlerASRequestHandlerRef(): Returns reference to the AS request handler.

Public Members:

uint16_t ProcessedClients: Counter for number of processed clients.

MemoryManager<char> BufferMemory: Memory manager for client data buffers.

Private Members:

ClientMap_t Clients: Map of active client connections.

struct epoll_event EpollEvent: Epoll event structure.

struct epoll_event EpollEvents[EPOLL_FD_COUNT_MAX]: Array of epoll events.

int EpollFD: Epoll file descriptor.

uint8_t LastProcessingIDStaticFS: Last processing ID for static filesystem.

uint8_t LastProcessingIDAppServer: Last processing ID for application server.

void *_SHMStaticFS: Static filesystem shared memory pointer.

void *_SHMPythonASMeta: Python AS metadata shared memory pointer.

void *_SHMPythonASRequests: Python AS requests shared memory pointer.

void *_SHMPythonASResults: Python AS results shared memory pointer.

ASRequestHandlerRef_t _ASRequestHandlerRef: Reference to AS request handler.

Configuration Classes

Configuration

Manages server configuration loaded from JSON configuration file.

class Configuration

Type Definitions:

typedef struct NamespaceProps_t

Namespace properties structure containing:

nlohmann::json JSONConfig - JSON configuration for namespace
std::shared_ptr<Filesystem> FilesystemRef - Reference to filesystem handler

typedef unordered_map<string, NamespaceProps_t> Namespaces_t: Map of namespace IDs to namespace properties.

typedef pair<string, NamespaceProps_t> NamespacePair_t: Pair of namespace ID and properties.

typedef vector<string> Mimetypes_t: Vector of supported MIME types.

typedef Namespaces_t& NamespacesRef_t: Reference to namespaces map.

Public Methods:

Configuration(): Constructor - Loads and parses configuration from config.json.

~Configuration(): Destructor - Cleans up configuration resources.

void mapStaticFSData(): Maps static filesystem data for all namespaces.

Public Members:

string RunAsUnixUser: Unix username to run the server as.

string RunAsUnixGroup: Unix group name to run the server as.

uint16_t RunAsUnixUserID: Unix user ID to drop privileges to.

uint16_t RunAsUnixGroupID: Unix group ID to drop privileges to.

string BasePath: Base path for web content.

string ServerAddress: Server IPv4 bind address.

uint16_t ServerPort: Server listen port.

Mimetypes_t Mimetypes: List of supported MIME types.

Namespaces_t Namespaces: Map of all configured namespaces.

Filesystem

Handles filesystem operations and virtual host file mappings.

class Filesystem

Type Definitions:

typedef struct FileProperties_t

File properties structure containing:

Filedescriptor_t Filedescriptor - File descriptor
unsigned int FileSize - Size of the file in bytes
string FileName - Name of the file
string FileExtension - File extension
string MimeType - MIME type of the file
string ETag - ETag for caching
string LastModifiedString - Last modified date string
string LastModifiedSeconds - Last modified in seconds

typedef unordered_map<string, const string> MimetypeRelations_t: Map of file extensions to MIME types.

typedef unsigned int Filedescriptor_t: File descriptor type.

typedef vector<string> FilelistPlain_t: Vector of file paths.

typedef pair<string, FileProperties_t> FileListExtendedPair_t: Pair of file path and properties.

typedef unordered_map<string, const FileProperties_t> FileListExtended_t: Map of file paths to properties.

Public Methods:

Filesystem(): Constructor - Initializes filesystem handler.

~Filesystem(): Destructor - Closes file descriptors and cleans up.

void initFiles(): Initializes and indexes all files in the configured path.

void processFileProperties(): Processes and extracts properties for all files.

FileProperties_t getFilePropertiesByFile(const string &File): Returns file properties for the specified file path.

bool checkFileExists(const string &File): Checks if a file exists in the filesystem.

string getFileEtag(const string &File): Returns the ETag for the specified file.

Public Members:

string Hostname: Virtual hostname for this filesystem.

string BasePath: Base path for web content.

string Path: Relative path from base path.

vector<string> Mimetypes: List of allowed MIME types.

Private Members:

FilelistPlain_t _Files: List of all file paths.

FileListExtended_t _FilesExtended: Map of file paths to extended properties.

string _CompletePath: Complete path (BasePath + Path).

Request Processing Classes

ASProcessHandler

Manages Python application server processes. Inherits from SHMPythonAS and CPU.

class ASProcessHandler

Type Definitions:

typedef struct ASProcessHandlerSHMPointer_t

Structure holding shared memory pointers:

void* PostASMetaPtr - AS metadata SHM pointer
void* PostASRequestsPtr - AS requests payload SHM pointer
void* PostASResultsPtr - AS results payload SHM pointer

Public Methods:

ASProcessHandler(): Constructor - Initializes AS process handler.

~ASProcessHandler(): Destructor - Cleans up AS process handler resources.

void forkProcessASHandler(ASProcessHandlerSHMPointer_t): Forks Python interpreter processes for application server.

void setTerminationHandler(): Sets up signal handler for graceful termination.

void setASProcessHandlerOffsets(VHostOffsetsPrecalc_t): Sets virtual host memory offsets for AS processes.

uint getASInterpreterCount(): Returns the number of Python interpreters spawned.

static void terminate(int): Static termination handler for AS processes.

static void registerChildPID(pid_t): Registers a child AS process PID.

Public Members:

string ReqPayloadString: Request payload string buffer.

boost::python::object PyClass: Python class object (when using Python backend).

Private Members:

VHostOffsetsPrecalc_t _VHostOffsetsPrecalc: Pre-calculated virtual host offsets.

ResultProcessor

Processes and sends results to clients. Inherits from SHMStaticFS, CPU, ResultOrder, and SHMPythonAS.

class ResultProcessor

Type Definitions:

typedef struct ResultProcessorSHMPointer_t

Structure holding shared memory pointers:

void* StaticFSPtr - Static FS SHM pointer
void* PostASMetaPtr - AS metadata SHM pointer
void* PostASRequestsPtr - AS requests SHM pointer
void* PostASResultsPtr - AS results SHM pointer

Public Methods:

ResultProcessor(): Constructor - Initializes result processor.

~ResultProcessor(): Destructor - Cleans up result processor resources.

pid_t forkProcessResultProcessor(ResultProcessorSHMPointer_t): Forks the result processor process and returns its PID.

void setTerminationHandler(): Sets up signal handler for graceful termination.

void setVHostOffsets(VHostOffsetsPrecalc_t): Sets virtual host memory offsets.

static void terminate(int): Static termination handler.

Private Methods:

void _processStaticFSRequests(uint16_t): Processes static filesystem requests from shared memory.

inline void _parseHTTPBaseProps(string&): Parses basic HTTP properties from request string.

uint16_t _processPythonASResults(): Processes Python application server results.

int _getFDFromParent(uint16_t fd): Receives file descriptor from parent process via Unix socket.

Private Members:

pid_t _ForkResult: Process ID of forked result processor.

int _FDPassingSocketFD: File descriptor for Unix domain socket.

VHostOffsetsPrecalc_t _VHostOffsetsPrecalc: Pre-calculated virtual host offsets.

Memory Management Classes

MemoryManager

Template class for aligned memory management with huge page support.

template<class T> class MemoryManager

Public Methods:

MemoryManager(uint16_t SegmentCount, uint16_t SegmentSize): Constructor - Allocates aligned memory with huge page support.

~MemoryManager(): Destructor - Frees allocated memory.

T *getNextMemPointer(): Returns pointer to the next memory segment.

T *getMemBaseAddress(): Returns the base address of allocated memory.

static constexpr size_t getAlignment(): Returns the alignment requirement for type T.

static bool isAligned(const void *ptr): Checks if a pointer is properly aligned for type T.

Public Members:

static constexpr size_t Alignment: Compile-time alignment requirement for type T.

Private Methods:

void allocateMemory(): Allocates memory and advises kernel to use huge pages.

void verifyAlignment(): Verifies memory alignment in debug builds.

T *getMemPointer(uint16_t SegmentOffset): Returns pointer to memory at the specified segment offset.

Private Members:

uint16_t SegmentCount: Number of memory segments.

uint16_t SegmentSize: Size of each segment.

uint16_t SegmentOffset: Current segment offset.

T *MemoryBaseAddress: Base address of allocated memory.

IPC and Shared Memory Classes

IPCHandler

Base class for inter-process communication and shared memory management.

class IPCHandler

Provides shared memory segment management for static filesystem requests.

Type Definitions:

typedef struct SHMData_t: Shared memory data structure for IPC.

Public Methods:

IPCHandler(): Constructor - Initializes IPC handler.

~IPCHandler(): Destructor - Cleans up IPC resources.

Shared Memory Layout:

Static FS SHM Segment #1:

Address 0x00: atomic_uint16_t StaticFSLock - Lock for static FS access
Address 0x02: uint16_t RequestCount - Number of requests
For each request:
- uint16_t ClientFD - Client file descriptor
- uint16_t HTTPVersion - HTTP version
- uint16_t RequestNr - Request number
- uint16_t PayloadLength - Payload length
- char[] Payload - Request payload data

SHMPythonAS

Shared memory handler for Python application server communication.

class SHMPythonAS

Provides shared memory segment management for Python AS requests and results.

Shared Memory Layout:

AS Metadata SHM Segment #2 (per interpreter):

atomic_uint16_t CanRead - Flag indicating request is ready
atomic_uint16_t WriteReady - Flag indicating ready for result
uint16_t ClientFD - Client file descriptor
uint16_t HTTPVersion - HTTP version
uint16_t HTTPMethod - HTTP method
uint16_t ReqNr - Request number
uint32_t ReqPayloadLen - Request payload length
uint32_t ResPayloadLen - Result payload length

AS Requests Payload SHM Segment #3:

char[] Payload - Request payload data (per interpreter segment)

AS Results Payload SHM Segment #4:

char[] Payload - Result payload data (per interpreter segment)

IPCHandlerAS

IPC handler specific to application server processes.

class IPCHandlerAS

Extends IPC functionality for application server communication.

Public Methods:

IPCHandlerAS(): Constructor - Initializes AS-specific IPC handler.

~IPCHandlerAS(): Destructor - Cleans up AS IPC resources.

Utility Classes

CPU

CPU affinity and binding utilities.

class CPU

Public Methods:

void bindToCPU(int core): Binds the current thread to the specified CPU core.

void bindToCPUs(std::vector<int> cores): Binds the current thread to multiple CPU cores.

Vector

Custom vector implementation with specialized operations.

class Vector

Public Methods:

void multiErase(std::vector<size_t> indices): Efficiently erases multiple elements by indices.

Helper Classes

Socket

Socket utility functions.

class Socket

Public Static Methods:

static void makeNonblocking(int fd): Makes a socket non-blocking by setting O_NONBLOCK flag.

FilesystemHelper

Filesystem helper utilities.

class FilesystemHelper

Public Static Methods:

static void GetDirListingByFiletype(vector<string> &FileListRef, const string Path, const string FileType): Recursively gets all files of a specific type from a directory.

String

String manipulation utilities.

class String

Public Static Methods:

static void split(string &StringRef, const string Delimiter, vector<string> &ResultRef): Splits a string by delimiter and stores results in vector.

static void rsplit(string &String, size_t StartPos, const string Delimiter, vector<string> &ResultRef): Reverse splits a string from a starting position.

static void hexout(string &String): Outputs string content in hexadecimal format for debugging.