GacUI/.github/KnowledgeBase/Index_VlppOS.md

VlppOS Knowledge Base

Project introduction remains in Index.md.

Choosing APIs

Locale Support

Cross-platform localization and globalization with culture-aware string operations and formatting.

• Use Locale::Invariant() or INVLOC macro for culture-invariant operations
• Use Locale::SystemDefault() for OS code page interpretation
• Use Locale::UserDefault() for user language and location settings
• Use Locale::Enumerate(locales) to get all supported locales
• Use Get*Formats methods for date-time format enumeration
• Use FormatDate and FormatTime for locale-aware date/time formatting
• Use Get*Name methods for localized week day and month names
• Use FormatNumber and FormatCurrency for locale-aware number formatting
• Use Compare for locale-aware comparison, and CompareOrdinal or CompareOrdinalIgnoreCase for ordinal comparison
• Use FindFirst, FindLast, StartsWith, EndsWith for normalized string searching
• Use InjectLocaleImpl to replace Locale implementation for testing and customization
• Use EjectLocaleImpl to eject an implementation and all later injections, or reset to default
• Use EnUsLocaleImpl class as platform-independent en-US fallback implementation

API Explanation

File System Operations

Cross-platform file and directory manipulation with path handling and content access.

• Use FilePath for path representation and manipulation
• Use GetPathDelimiter, operator/, GetName, GetFolder, GetFullPath, GetRelativePathFor for path operations
• Use IsFile, IsFolder, IsRoot to determine path object types
• Use File class for existing files or paths where a file will be written
• Use ReadAllTextWithEncodingTesting, ReadAllTextByBom, ReadAllLinesByBom for text reading
• Use WriteAllText, WriteAllLines for text writing
• Use Exists, Delete, Rename for file operations
• Use Folder class for directory operations when FilePath::IsFolder or FilePath::IsRoot returns true
• Use GetFolders, GetFiles for directory content enumeration
• Use Create(bool recursively), Delete(bool recursively), Rename for folder operations
• Use InjectFileSystemImpl to replace file system implementation for testing and customization
• Use EjectFileSystemImpl to eject an implementation and all later injections, or reset to default

API Explanation

Stream Operations

Unified stream interface for file, memory, and data transformation operations with encoding support.

• Use IStream interface for all stream operations
• Use FileStream for file I/O with ReadOnly, WriteOnly, ReadWrite modes
• Use MemoryStream for in-memory buffer operations
• Use MemoryWrapperStream for operating on existing memory buffers
• Use EncoderStream and DecoderStream for data transformation pipelines
• Use IsAvailable, CanRead, CanWrite, CanSeek, CanPeek, IsLimited for capability checking
• Use Read, Write, Peek, Seek, SeekFromBegin, SeekFromEnd, Position, Size for stream operations
• Use Close for resource cleanup (automatic on destruction)

API Explanation

Encoding and Decoding

Text encoding conversion between different UTF formats with BOM support and binary data encoding.

• Use BomEncoder and BomDecoder for UTF encoding with BOM support
• Use UtfGeneralEncoder<Native, Expect> and UtfGeneralDecoder<Native, Expect> for UTF conversion without BOM
• Use Utf8Encoder, Utf8Decoder, Utf16Encoder, Utf16Decoder, Utf16BEEncoder, Utf16BEDecoder, Utf32Encoder, Utf32Decoder for specific UTF conversions
• Use MbcsEncoder and MbcsDecoder for ASCII/MBCS conversion
• Use TestEncoding for automatic encoding detection
• Use Utf8Base64Encoder and Utf8Base64Decoder for Base64 encoding in UTF-8
• Use LzwEncoder and LzwDecoder for data compression
• Use CopyStream, CompressStream, DecompressStream helper functions

API Explanation

Additional Streams

Specialized stream types for caching, recording, and broadcasting data operations.

• Use CacheStream for performance optimization with non-random accessed data, although it supports random accessing if the underlying stream does
• Use RecorderStream for copying data from one stream to another during reading
• Use BroadcastStream for writing the same data to multiple target streams
• Use Targets() method to manage BroadcastStream destinations

API Explanation

Multi-threading

Cross-platform threading primitives and synchronization mechanisms for concurrent programming.

• Use ThreadPoolLite::Queue and ThreadPoolLite::QueueLambda for thread pool execution
• Use TaskQueue when queued work must run on one blocking task loop instead of the thread pool
• Use Thread::Sleep for thread pausing
• Use Thread::GetCurrentThreadId for thread identification
• Use Thread::CreateAndStart only when thread pool is insufficient

API Explanation

Synchronization Primitives

Non-waitable synchronization objects for protecting shared resources in multi-threaded environments.

• Use SpinLock for protecting very fast code sections
• Use CriticalSection for protecting time-consuming code sections
• Use ReaderWriterLock for multiple reader, single writer scenarios
• Use Enter, TryEnter, Leave for manual lock management
• Use SPIN_LOCK, CS_LOCK, READER_LOCK, WRITER_LOCK macros for exception-safe automatic locking
• Use ConditionVariable with SleepWith, SleepWithForTime for conditional waiting
• Use WakeOnePending, WakeAllPendings for condition variable signaling

API Explanation

Waitable Objects

Cross-process synchronization objects that support waiting operations with timeout capabilities.

• Use Mutex for cross-process mutual exclusion
• Use Semaphore for counting semaphore operations across processes
• Use EventObject for event signaling between threads, or across processes on Windows
• Use Create and Open methods for establishing named synchronization objects
• Use Wait, WaitForTime for blocking operations with optional timeout
• Use WaitAll, WaitAllForTime, WaitAny, WaitAnyForTime for multiple object synchronization
• Use Signal, Unsignal for event object state management
• Use Release for releasing mutex and semaphore ownership

API Explanation

Inter-Process Network Protocols and Channels

Production-usable asynchronous text-protocol and typed named-channel abstractions. Every concrete network-protocol implementation supplied by this repository, including stdio redirection and the async-socket-based Mini HTTP transport, is testing-only; production applications should provide their own INetworkProtocol* implementation.

• Use INetworkProtocolServer, INetworkProtocolClient, INetworkProtocolConnection and INetworkProtocolCallback for asynchronous WString messages.
• Use IChannelServer<TPackage>, IChannelClient<TPackage>, IChannel<TPackage> and IChannelReader<TPackage> for typed named channels with client ids, direct sends, broadcasts and batched writes.
• Use NetworkProtocolChannelServer<TPackage, TSerialization, TServerBase>, NetworkProtocolChannelClient<TPackage, TSerialization> and NetworkProtocolLocalChannelClient<TPackage, TSerialization> to run the channel implementation over a production-ready custom protocol.
• Use vl::inter_process::stdio_redirection::StdioRedirectionServer, vl::inter_process::stdio_redirection::StdioRedirectionClient and vl::inter_process::stdio_redirection::StdioRedirectionConnection only for testing when a child process should exchange framed protocol messages through stdin and stdout.
• Use vl::inter_process::async_tcp_socket::SocketHttpServer and vl::inter_process::async_tcp_socket::SocketHttpClient only for testing as the portable Mini HTTP implementation of the raw network-protocol interfaces.

API Explanation

Async-Socket-Based Mini HTTP API

Testing-only layered loopback TCP and HTTP/1.1 APIs for asynchronous binary streams, parsed request/response connections and prefix-dispatched Mini HTTP services. Do not use these APIs in production code.

• Use vl::inter_process::async_tcp_socket::IAsyncSocketServer, vl::inter_process::async_tcp_socket::IAsyncSocketClient, vl::inter_process::async_tcp_socket::IAsyncSocketConnection, vl::inter_process::async_tcp_socket::IAsyncSocketCallback and vl::inter_process::async_tcp_socket::AsyncSocketBuffer for asynchronous loopback byte streams. Each server and client exposes its immutable construction port through GetPort(), and a client creates a fresh transport-preserving lane through CreateSameEndpointClient().
• Use the platform-neutral vl::inter_process::async_tcp_socket::CreateDefaultAsyncSocketServer and vl::inter_process::async_tcp_socket::CreateDefaultAsyncSocketClient factories at the composition boundary.
• Use vl::inter_process::async_tcp_socket::windows_socket::AsyncSocketServer / vl::inter_process::async_tcp_socket::windows_socket::AsyncSocketClient, vl::inter_process::async_tcp_socket::linux_socket::AsyncSocketServer / vl::inter_process::async_tcp_socket::linux_socket::AsyncSocketClient, or vl::inter_process::async_tcp_socket::macos_socket::AsyncSocketServer / vl::inter_process::async_tcp_socket::macos_socket::AsyncSocketClient for the current platform.
• Use vl::inter_process::async_tcp_socket::HttpRequest, vl::inter_process::async_tcp_socket::HttpResponse, vl::inter_process::async_tcp_socket::HttpRequestServer, vl::inter_process::async_tcp_socket::HttpRequestClient, vl::inter_process::async_tcp_socket::IHttpRequestConnection and vl::inter_process::async_tcp_socket::IHttpRequestCallback for binary-safe sequential HTTP/1.1 exchanges.
• Use vl::inter_process::async_tcp_socket::SocketHttpServerApi, vl::inter_process::async_tcp_socket::SocketHttpRequestContext and vl::inter_process::async_tcp_socket::SocketHttpClientApi for prefix-dispatched Mini HTTP request/response work; inject socket dependencies explicitly, derive the port from the injected socket, reuse the same server pointer when multiple prefixes must share one listener, and treat client-side 404 as a terminal ResponseNotFound error.

API Explanation

Terminal User Interface

Cross-platform owner-thread terminal takeover with input, resize and timer callbacks, a validated cell buffer, Unicode-aware character placement, box-drawing primitives and deterministic backend injection for tests.

• Use TUI::TryGetConsoleSize to query the visible terminal before startup.
• Use TUI::InstallListener, TUI::Start, TUI::RunOneCycle, TUI::Stop, TUI::IsInUse, TUI::IsStopRequested and TUI::UninstallListener for lifecycle and owner-thread event processing.
• Use TuiStartOptions, TuiColorMode and TUI::GetColorMode to request and inspect terminal color emission.
• Use shared vl::presentation::VKEY and input types from VlppOS/Source/TUI/TUITypes.h for key identities and independent Alt/OS Super; GacUI consumes these declarations.
• Use ITuiCallback with vl::presentation::WindowMouseInfo, vl::presentation::NativeWindowKeyInfo and vl::presentation::NativeWindowCharInfo from VlppOS/Source/TUI/TUITypes.h for startup, shutdown, resize, input and timer callbacks.
• Use TUI::StartTimer and TUI::StopTimer for deadline-driven callbacks on the TUI owner thread.
• Use TUI::GetBuffer, TUI::GetBufferWidth, TUI::GetBufferHeight and TUI::RenderBuffer for retained cell-buffer rendering.
• Use TuiPixel, TuiPixelGlyph, TuiColor and TUI::MeasureChar to represent and validate terminal cells and scalar widths.
• Use TuiCharPixel, TuiTextStyle and TuiPrintOptions for character cells with bold, italic, underline and strikeline styles.
• Use TUI::PrintChar, TUI::DrawLineV, TUI::DrawLineH, TUI::DrawRect and TUI::Clear for clipped drawing on the active buffer or a caller-owned buffer.
• Use TuiClipper from VlppOS/Source/TUI/TUI.h for half-open drawing clips that preserve original primitive geometry and width-two character invariants.
• Use TuiLineOptions::foregroundColorBlending and TuiRectOptions::foregroundColorBlending from VlppOS/Source/TUI/TUI.h for destination-dependent foreground colors on painted line and border cells.
• Use vl::console::unittest::ScopedTuiBackend with vl::console::unittest::ITuiBackend for deterministic TUI tests.

API Explanation

Design Explanation

Implementing an Injectable Feature

• Linked-list based dependency injection mechanism enabling runtime replacement and extension of feature implementations while maintaining delegation capabilities
• Three core components: IFeatureImpl base interface, FeatureImpl<TImpl> template for type-safe delegation, and FeatureInjection<TImpl> manager for chain operations
• Standard implementation pattern with interface definition, default implementation, global management functions using static local variables for thread-safe singleton behavior
• Delegation mechanism through Previous() method allowing partial overrides and full delegation with LIFO injection structure and cascading ejection behavior
• Critical lifecycle guarantees where EndInjection only called during explicit operations, and restriction of injection/ejection to application-level code for proper ordering
• Real-world implementation demonstrated through DateTime system with platform-specific implementations and testing integration using mock implementations

Design Explanation