Well, I can help by shortly describing the structure of the project. But notice that because of using FastCGI protocol, AsmBB is a little bit more complex than usual for beginner assembly programmer.

The simple CGI web application (for example my CMS MiniMagAsm) works by short living CGI processes. They are started by the web server, receive the HTTP request by reading STDIN, write the response (e.g. HTML) to STDOUT and terminate.

The FastCGI application works a little bit different. At first it works all the time and listens for connections on some socket. The web server connects to this socket and sends the request. Then the FastCGI application sends back the response using the same connection. Serving multiply requests on the same connection and multiply connections are possible. Also, the web server can start several instances of the FastCGI application. It is all about a performance. So, the structure of AsmBB:

Everything starts in engine.asm, line:123 - the label start:. Here the engine initializes its environments and opens the SQLite database with the forum data. Then it calls the procedure Listen (line: 163) that is the main loop of the program. It returns only when the engine terminates. After retuning from Listen, the program closes the database, finalizes its works and exits.

The procedure Listen is defined in the source file fcgi.asm:166. This is the code, that handles FastCGI protocol. It simply listens for connections from the web server and on connection creates a thread that to serve the request and continues to listen. The thread is started in the procedure procServeRequest in fcgi.asm:347.

This thread, receives the request information on the socket and collects it for future processing.

Once the whole information is collected - i.e. the HTTP reques, the POST data (if any) and the environment parameters, the procedure ServeOneRequest is called. It is actually the "business logic" code that makes the application to act as a web forum.

ServeOneRequest returns the response (e.g. HTML code, images, etc.) that is returned to the web server, according to FastCGI protocol. After completing the request, the thread terminates or stays waiting for another request. It depends on how the web server can multiplex the requests on the FastCGI connection.

ServeOneRequest is located in the file commands.asm:127. It analyzes the request URL and the request type (GET, POST) and decides how to serve it. For example, it can return some file directly, or read the information from the database, or store some information in the database.

The URL analyze is important and located on commands.asm:427 - it dispatches the control depending on the URL elements. The addresses of the different procedures are loaded to ECX and later called (label .exec_command, line: 598).

Later you can browse these procedures. They are located in different files, serving different aspects of forum engine. For example, the procedure ListThreads threadlist.asm creates the list of threads on the front page of the forum.

The procedure ShowThread showthread.asm displays one thread. And so on.

Notice, that AsmBB widely uses the library FreshLib. You can read more in FreshLib reference and FreshLib user guide, but unfortunately the documentation is far from perfect.

In order to better browse the big code, scattered across multiply files, I would suggest using Fresh IDE code browsing features. Read more in the following article: Tips and tricks. Especially useful if the feature "Goto definition" (Ctrl+D) that will jump you at the line where some label is defined. The cross reference is also useful (Ctrl+R).

FreshLib user guide

How AsmBB Engine Works - Detailed Explanation

Overview

engine.asm is the main entry point and core infrastructure of the AsmBB forum system. It's written entirely in assembly language and serves as a high-performance FastCGI web forum engine with real-time capabilities.

Architecture Components

1. Application Structure** ` ┌─────────────────────────────────────────────────────────────┐ │ AsmBB Engine │ ├─────────────────────────────────────────────────────────────┤ │ 1. Main Entry Point (start) │ │ 2. Signal Handlers (Exception/Termination) │ │ 3. Database Layer (SQLite with custom functions) │ │ 4. Debug System (SQLite tracking, monitoring) │ │ 5. FastCGI Interface (Web server communication) │ │ 6. Real-time Events (Server-Sent Events) │ └─────────────────────────────────────────────────────────────┘ `

Detailed Workflow

Phase 1: Application Startup**

` start: ┌─────────────────────────────────────────────┐ │ 1. Initialize FreshLib System │ │ - Memory management │ │ - String handling │ │ - Basic OS abstractions │ └─────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────┐ │ 2. SQLite Setup │ │ - Configure debug wrappers (optional) │ │ - Set up signal handlers │ │ - Initialize SQLite library │ └─────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────┐ │ 3. Database Initialization │ │ - Create or open database │ │ - Run initialization script │ │ - Handle encryption (if needed) │ └─────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────┐ │ 4. Database Optimization │ │ - Register custom SQL functions │ │ - Set performance pragmas │ │ - Configure for web workload │ └─────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────┐ │ 5. Real-time System Setup │ │ - Initialize IPC for events │ │ - Start SSE service thread │ └─────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────┐ │ 6. Enter FastCGI Main Loop │ │ - Accept incoming requests │ │ - Create worker threads │ │ - Process HTTP requests │ └─────────────────────────────────────────────┘ `

Phase 2: Request Processing Flow**

` FastCGI Request Flow: ┌─────────────────────────────────────────────┐ │ 1. Web Server → FastCGI Socket │ └─────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────┐ │ 2. Listen() Function │ │ - Accept connection │ │ - Create thread (procServeRequest) │ │ - Continue accepting │ └─────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────┐ │ 3. Request Thread │ │ - Parse FastCGI protocol │ │ - Extract parameters/POST data │ │ - Call ServeOneRequest() │ └─────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────┐ │ 4. Route to Handler │ │ - Parse URL path │ │ - Determine command │ │ - Call appropriate function │ │ (e.g., ListThreads, ShowThread, etc.) │ └─────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────┐ │ 5. Database Operations │ │ - Execute SQL queries │ │ - Process results │ │ - Generate response │ └─────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────┐ │ 6. Template Rendering │ │ - Load template file │ │ - Process template directives │ │ - Insert data values │ │ - Output HTML response │ └─────────────────────────────────────────────┘ `

Phase 3: Real-time Event System**

` Event Broadcasting Flow: ┌─────────────────────────────────────────────┐ │ 1. Activity Occurs │ │ - User posts message │ │ - User logs in/out │ │ - Chat message │ └─────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────┐ │ 2. AddActivity() Call │ │ - Create JSON activity message │ │ - AddEvent() to event queue │ └─────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────┐ │ 3. SSE Service Thread │ │ - Monitor event queue │ │ - Format as Server-Sent Events │ │ - Broadcast to connected clients │ └─────────────────────────────────────────────┘ `

Key Technical Features

1. Database Configuration**

The engine uses SQLite with specific optimizations for web workloads:

assembly

SetDatabaseMode: PRAGMA foreign_keys = TRUE ; Data integrity PRAGMA recursive_triggers = TRUE ; Complex operations PRAGMA threads = 2 ; Multi-threading PRAGMA journal_mode = WAL ; Write-Ahead Logging PRAGMA synchronous = OFF ; Maximum performance `

Why these settings:** - WAL mode**: Allows concurrent reads during writes - Async writes**: Faster for high-traffic web scenarios - Multi-threading**: Better CPU utilization - Foreign keys**: Ensures data consistency

2. Memory Management**

The engine uses FreshLib's custom memory management: - String pooling**: Reduces memory allocations - Gap buffers**: Efficient text manipulation - Reference counting**: Automatic cleanup

3. Signal Handling**

Robust error handling through signal handlers: - SIGTERM**: Graceful shutdown (OnForcedTerminate) - SIGSEGV/SIGFPE**: Exception handling (OnException) - Cleanup**: Proper resource release and database closing

4. Debug System**

Comprehensive debugging infrastructure: - SQLite tracking**: Monitors unfinalized statements - Memory monitoring**: Tracks string allocations - Performance metrics**: Thread count, load detection - Admin interface**: Web-based debug information

Real-time Architecture

Server-Sent Events (SSE)**

The engine implements real-time updates using SSE:

` Client Request → EventsRealTime() → InitEventSession() │ │ ▼ ▼ Establish SSE connection ← sseServiceThread ← Event Queue │ │ ▼ ▼ Stream updates → JSON format → HTML5 EventSource API `

Event Types:** - evMessage: Chat messages - evUsersOnline: Online user list - evUserActivity: User actions (posting, browsing, etc.)

Performance Optimizations

1. Assembly Language Benefits** - Zero overhead**: No runtime library bloat - Direct memory access**: Optimized data structures - System calls**: Minimal abstraction layers

2. Template Engine** - Compiled templates**: Pre-parsed for fast execution - Hash table lookups**: O(1) field access - Gap buffers**: Efficient string manipulation

3. Database Efficiency** - Connection pooling**: Reuses database connections - Prepared statements**: Reduced SQL parsing overhead - Batch operations**: Minimized round trips

Security Features

1. Input Validation** - Parameter checking**: Type and format validation - SQL injection prevention**: Parameterized queries - XSS protection**: HTML encoding by default

2. Access Control** - Session management**: Secure user authentication - Permission system**: Role-based access control - CSRF protection**: Request validation tokens

3. Data Protection** - Database encryption**: Optional file encryption - Secure defaults**: Safe configuration options - Memory safety**: Proper buffer management

Error Handling and Resilience

1. Graceful Degradation** - Database failures**: Retry mechanisms with timeouts - Resource exhaustion**: Load shedding and throttling - Network issues**: Proper connection cleanup

2. Monitoring and Diagnostics** - Comprehensive logging**: Error tracking and debugging - Performance metrics**: System health monitoring - Admin tools**: Real-time status and control

Why This Architecture Works

1. Performance** - Assembly optimization**: Maximizes hardware utilization - Efficient algorithms**: O(1) lookups, minimal allocations - Concurrent processing**: Multi-threaded request handling

2. Reliability** - Signal handling**: Robust error recovery - Resource management**: Proper cleanup and tracking - Database integrity**: ACID compliance with SQLite

3. Scalability** - Thread pool**: Configurable concurrency limits - Event-driven architecture**: Non-blocking I/O - Modular design**: Easy feature addition

4. Maintainability** - Clear separation**: Database, web, and UI layers - Debug infrastructure**: Comprehensive monitoring tools - Modular includes**: Organized code structure

This engine demonstrates how assembly language can be used to create a modern, high-performance web application with real-time capabilities, while maintaining the reliability and security expected of a production forum system.

This assembly file, engine.asm, is the main entry point and core engine for AsmBoard**, a message board (forum) written entirely in x86 assembly language. It uses the FreshLib** library to abstract operating system differences and SQLite** for its database.

It's designed to run as a backend service using the FastCGI** protocol, which means a web server (like Nginx or Apache) forwards web requests to this running application.

Here is a detailed breakdown of how it works.

-

Core Functionality

The file's primary responsibilities are:

Initialization:** Setting up the application, signal handlers, and the SQLite database.

Service Threads:** Launching background threads, specifically for Server-Sent Events (SSE) to handle real-time updates (like chat or new post notifications).

Main Loop:** Entering the main FastCGI Listen loop, where it waits for and processes incoming web requests.

Debug System:** Providing a comprehensive, built-in debugging system to track SQLite resource leaks and system status. This is a major feature of this specific file, enabled by options.DebugSQLite = 1.

Shutdown:** Handling graceful shutdown signals (like SIGTERM) to close the database and clean up resources properly.

The include directives at the top show the full scope of the AsmBoard project, pulling in modules for every feature, including:

Forum Features:** threadlist.asm, showthread.asm, edit.asm, delete.asm, search.asm

User Features:** accounts.asm, userinfo.asm, users_online.asm

Real-time:** chat.asm, realtime.asm, sse_service.asm

Core:** http.asm, fcgi.asm, sqlite3.asm

-

Program Flow (The start: label)

This is the main execution path when the application is launched.

1. FreshLib Init:** InitializeAll sets up the FreshLib environment. 2. SQLite Debugger Setup:**

The code checks the options.DebugSQLite flag, which is set to 1 (on) in this file.

Because it's on, it calls InitSQLStmtDebugger. This "hooks" the standard SQLite functions.

Global function pointers sqlitePrepare_v2 and sqliteFinalize are set to point to the custom wrappers my_sqlitePrepare_v2 and my_sqliteFinalize. This is done to track every SQLite statement that is created and destroyed. 3. Signal Handlers:**

SetSegmentationFaultHandler: Catches crashes (like SIGSEGV) and routes them to the OnException procedure.

SetForcedTerminateHandler: Catches graceful shutdown signals (like SIGTERM) and routes them to the OnForcedTerminate procedure. 4. SQLite Initialization:**

sqliteConfig, SQLITE_CONFIG_SERIALIZED: Configures SQLite to be thread-safe.

sqliteInitialize: Loads the SQLite library.

OpenOrCreate: This custom function attempts to open the database file (`./board.sqlite`). If the file doesn't exist, it uses the SQL code from create.sql (loaded into sqlCreateDB) to create the entire database schema. 5. Encryption Check:**

The OpenOrCreate function returns 1 in eax if the database is encrypted and needs a key.

If so, it sets the fNeedKey flag. 6. Database Configuration:**

SQLiteRegisterFunctions: Registers custom functions (defined in sqlite3.asm) so they can be called from within SQL queries.

SetDatabaseMode: This procedure is called to set optimal PRAGMAs (settings) for the database. 7. IPC and Background Threads:**

InitEventsIPC: Initializes the Inter-Process Communication system, which is used to coordinate between threads.

ThreadCreate, sseServiceThread, 0: Starts the Server-Sent Events (SSE)** service in a new thread. This thread manages real-time push notifications to clients. 8. Main Loop:**

stdcall Listen: This is the heart of the application**. It's the main FastCGI loop. The program's execution stops here and waits for the web server to send a request.

When a request comes in, this function (or a new thread it spawns) handles it. It only exits this loop when a shutdown is triggered. 9. Shutdown Sequence (`start.terminate`):**

This code block is jumped to when Listen exits or when a signal handler forces a shutdown.

Database Close Retry Loop:** It tries to close the SQLite database (`sqliteClose`). This might fail with SQLITE_BUSY if other threads are still finishing queries.

The code will Sleep for 10ms and retry up to 30 times (300ms total).

If it still can't close the database, it prints an error message to STDERR.

sqliteShutdown: Shuts down the SQLite library.

FinalizeAll / TerminateAll: Cleans up FreshLib and exits the process.

-

Key Procedures

SetDatabaseMode This procedure is critical for performance. It sets several SQLite PRAGMAs:

sqliteBusyTimeout, 5000: If the database is locked, wait up to 5 seconds before giving up.

PRAGMA foreign_keys = TRUE: Enforces data integrity.

PRAGMA journal_mode = WAL: Write-Ahead Logging**. This allows "readers" (users browsing) and "writers" (users posting) to run concurrently.

PRAGMA synchronous = OFF: Disables "full sync" on writes for maximum performance.

Shutdown Handlers (`OnForcedTerminate`, OnException) These procedures handle system signals for shutting down. 1. They both call __ForceTerminate. 2. They set the process exit code (0 for normal, 1 for exception). 3. They jmp directly to the start.terminate cleanup block.

__ForceTerminate is the function that does the real work:

lock inc [fEventsTerminate]: Atomically sets a global flag to signal all threads to terminate.

stdcall SignalNewEvent: Wakes up any sleeping threads so they can check the termination flag.

stdcall SocketClose, [STDIN]: In FastCGI, STDIN is the socket for receiving requests. Closing it tells the web server this backend process is dead.

-

SQLite Debugging System

Because options.DebugSQLite is enabled, a large portion of this file is dedicated to a powerful debug system for finding resource leaks.

How it works:** 1. Hooking:** InitSQLStmtDebugger makes the program call my_sqlitePrepare_v2 and my_sqliteFinalize instead of the real SQLite functions. 2. Tracking:**

my_sqlitePrepare_v2: Every time an SQL query is "prepared," this wrapper function logs the new statement handle and the code address of the caller into a global array (`ptrSQList`).

my_sqliteFinalize: Every time a statement is "finalized," this wrapper removes that statement handle from the ptrSQList array before calling the real _sqliteFinalize. 3. Reporting (`DebugInfo` / ListSQLiteStatus):**

The DebugInfo procedure is a special page for admins that calls ListSQLiteStatus.

ListSQLiteStatus builds an HTML debug page that shows:

Not finalized SQLite statements:** It iterates through the ptrSQList. Any statements still in this list are leaks. It prints the statement handle and the caller's address.

SSE listeners:** Shows how many users are currently connected to the real-time event service.

Engine overload:** Checks the current thread count.

StrLib statistics:** Dumps the string-memory manager, including a list of allocated strings.