What is Tinox?

Tinox is an independently developed, statically typed programming language that compiles directly to native machine instructions. The language combines a Java-like, annotation-driven syntax with the performance advantages of an LLVM-based compiler and a runtime system written in C.

The main focus is on the simple development of high-performance HTTP REST services: a controller handler requires only a few lines of code, and the built-in HTTP server is based on epoll and SO_REUSEPORT – technologies also used in production-ready web servers such as Nginx.

import tinox.core.http_server
import tinox.core.json

class SortController
{
    @POST
    @Path("/sort")
    @Consumes(MediaType.APPLICATION_JSON)
    @Produces(MediaType.APPLICATION_JSON)
    fn sort(ctx: HttpContext) -> Nothing
    {
        const root: JsonValue = Json.parse(ctx.request.body)
        const numbers: List<Int64> = Json.intArrayFromJson(root.getField("numbers"))
        ctx.response.body = Json.intArrayWrap("sorted", numbers.sort())
    }
}

This code represents a fully functional REST endpoint – no framework configuration overhead, no XML files, no boilerplate.

Technical Fundamentals

LLVM as Compiler Backend

The Tinox compiler does not generate native machine instructions directly, but rather LLVM Intermediate Representation (LLVM IR) – a platform-independent, typed assembly language. The LLVM toolchain then handles the optimization and translation to machine code.

LLVM is also used by Clang (C/C++), Rust, Swift, Julia, and Kotlin Native – it is one of the most mature compiler backends in the industry.

Rust as Implementation Language

The entire compiler – lexer, parser, type checker, code generator, and LSP server – is implemented in Rust. This brings the following advantages:

• Safety No undefined behavior, no memory errors in the compiler itself
• Performance Fast compile times of the compiler (no GC pauses)
• Concurrency Thread-safe data structures (DashMap) for the LSP server

C as Runtime System

The runtime system (runtime.c) is written in C and provides all operating system-level functions: memory management, strings, arrays, maps, file I/O, networking, and the HTTP server. C functions are called directly from LLVM IR – no ABI overhead through wrapper layers.

Key Concepts

Statement Termination

A statement ends at the end of its line – there is no statement terminator. A ; that terminates a statement is a hard compile error (“semicolons were removed”), and several statements cannot share a line. The only remaining ; separates the parts of a C-style for (init; cond; update) header.

A statement continues on the next line only if the line ends with a binary operator, a comma or an opening bracket, or if the next line starts with . (method chains). Inside ( ) and [ ] newlines are plain whitespace. A line starting with (, [, - or + directly after a complete expression is a hard error – the compiler never guesses whether it continues the previous line. Enum variants are written one per line.

const total = first +
    second +
    third

const name = user
    .profile()
    .displayName()

Components Overview

Tinox consists of several Rust crates (libraries) that together form the compiler and tooling, plus the C runtime system and the standard library written in Tinox itself.

Compiler Pipeline

The Tinox compiler transforms a .tnx source file in several steps into an executable native binary:

Runtime (C Runtime System)

The core of the Tinox runtime system is runtime/runtime.c (~1,700 lines of C code). It provides all primitives that the generated LLVM IR accesses directly.

Memory Management

Tinox uses the Boehm Garbage Collector (libgc) for automatic memory management. The GC is conservative: it scans the stack and registers for pointers and frees objects that are no longer reachable – without the developer having to call free() explicitly. With GC_THREADS it is fully thread-safe and works correctly with the epoll-based HTTP server thread pool.

For frequent operations (sort, JSON parsing), thread-local static buffers that are allocated once and then reused – this completely eliminates malloc overhead in the request-critical path.

Collections

Async & Concurrency

The concurrency model is based on POSIX threads (pthreads). spawn creates a real OS thread. Channels internally use a linked-list queue with mutex and condition variable.

Task lifetime, deadlines and cancellation

scope { ... } owns its lexical spawns. A plain spawn belongs to its spawning thread's lifetime; that thread joins its remaining children before finishing. On process exit, remaining joinable children are cancelled and joined. Failures are rethrown by await, or at scope exit if unobserved; additional failures are reported on stderr. A body's own error wins. Repeated awaits cache the same result or error while the owner lives. After the owning scope closes, handles expire and further use fails visibly. Keep tasks inside their owner; return the awaited value instead of a task.

try {
    scope {
        taskSetDeadline(250) // Duration from now, in monotonic milliseconds.
        const task: Task<String> = spawn Main::load()
        println(await task)
    }
} catch (e: String) { println(e) }

Cancellation also wakes sleep/sleep_ms, blocked channel recv, and await (check latency about 10 ms, excluding scheduling). Tokens propagate to child tasks and nested scopes. Scope failure cancels unfinished siblings; body errors remain primary. An explicitly cancelled task still reports cancellation unless awaited and caught. Expected cancellation during process shutdown is successful.

Cancellation uses normal exception unwinding: finally and defer run in their usual order; a child's transaction rolls back before its join completes. Transactions are thread-local and never inherited. Put a scope inside a transactional method to join before commit, and put parent resource cleanup outside the scope so children finish first.

No asynchronous thread termination is used. Native blocking I/O, database calls and CPU loops without checkpoints are not automatically interruptible. Use resource-specific stop/close operations or taskWaitReadable; after five seconds of ignored cancellation during scope shutdown, the runtime fails visibly instead of hanging silently. Explicit await of a cancelled task and a service shutdown request have the same five-second watchdog. With @Service, its configured common shutdown deadline replaces the standalone five-second shutdown watchdog; see the service lifecycle below. Detached workers are explicitly outside structured joining.

Legacy Int64 handle storage/await remains temporarily compatible for published packages. New code and task-control operations require Task<T>. Invalid/expired handles and cyclic awaits fail with a diagnostic; integer handles are deprecated.

Coordinated service lifecycle

Add @Service(startupMs, shutdownMs) to class Main to enable coordinated startup, health reporting and graceful shutdown. Both durations are optional positive integer milliseconds (defaults: 30000 and 5000; maximum: 3600000). The coordinator starts before database initialization and eager DI. Existing programs opt into this contract explicitly.

@ApplicationComponent
@Synchronized
class Resources {
    @OnStart
    fn start() -> Nothing { /* Initialize resources before listeners start. */ }
    @Readiness
    fn ready() -> Bool { return true }
    @Liveness
    fn live() -> Bool { return true }
    @OnStop
    fn stop() -> Nothing { /* Dispose resources after callbacks and tasks finish. */ }
}

@Service(30000, 5000)
class Main {
    fnc main() -> Int32 { return 0 }
}

Import the component and annotated controllers/endpoints from the entry file. Hooks are synchronous instance methods without parameters, on non-generic @ApplicationComponent/@Startup classes without inheritance. Start hooks run after injected dependencies' hooks, then by class/method name; stop hooks run in reverse order. Each hook joins its spawned children before the next step. All initialized owners receive stop hooks even after a startup failure; cleanup continues after errors, preserves the first failure and exits nonzero. Protect mutable state shared with health checks and callbacks using @Synchronized.

States are initializing → starting → ready, with unready for failed health contributions, then draining → stopping → stopped (or failed). Readiness requires completed initialization/start hooks, bound required listeners, consumer handshakes and successful readiness/liveness contributions. Returning from Main is not a readiness barrier; with listeners, it leaves the service running. Without listeners, returning requests shutdown.

Generated HTTP and HTTP/3 servers reserve GET /health/live and GET /health/ready: HTTP 200 or 503 with JSON state, readiness, liveness and monotonic startedMs, readyMs, shutdownMs. Started means managed bootstrap entry; ready is the first successful health pass, not process creation or banner timing. Health contributions run periodically on the coordinator and should be quick. Unready startup exceeding its budget fails visibly. A later false health result changes health, without restarting the process.

serviceState(), serviceStatusJson(), serviceIsReady(), serviceIsLive(), serviceIsStopping() and the three timestamp getters serviceStartedMs()/serviceReadyMs()/serviceShutdownMs() expose the same state. serviceAwaitReady(ms) returns Bool; serviceBoundPort(index) reports the actual port of an auto-run task in bootstrap-plan order (-1 before binding or for a broker). tinox explain --bootstrap Main.tnx --json includes deadlines, hook order, tasks and shutdown policy.

SIGTERM, SIGINT, serviceRequestShutdown() and taskRequestShutdown() mark the service unready and stop admission. Accepted HTTP responses and broker acknowledgements finish; WebSockets send close code 1001 and run OnClose. Listeners/workers join before remaining structured children are cancelled/joined, reverse stop hooks run and database pools close. serviceAwaitShutdown() lets Main wait for the stop request. One common shutdown deadline covers every stage; expiry terminates the process with status 1, including blocked native I/O or hooks. No asynchronous thread cancellation is used. Explicitly detached user tasks remain outside structured joining.

Use an exec-form container entrypoint so signals reach tinox. Configure a startup probe and readiness/liveness probes against the health paths, and give the orchestrator a termination grace period longer than the shutdown budget. CLI @Command and @TinoxUIApp entrypoints cannot currently combine with @Service; compilation rejects them visibly.

Shared application state

@ApplicationComponent creates one lazy singleton per component class; @Startup eagerly creates that same kind of singleton before main. Generated providers serialize construction, field defaults, recursive dependency injection and publication. Every concurrent provider caller sees the same fully initialized instance. Providers do not invoke user constructors. This initialization guarantee does not serialize later mutation.

HTTP workers and independently spawned REST, WebSocket and AMQP components can execute concurrently. Put request data in @HttpRequestScoped owners, and inject application services into them. Capturing a request-scoped dependency in a singleton shares that object; refreshing a singleton controller's injected field during dispatch is unsafe for per-request isolation. The compiler warns about captive request state and exposed or unguarded mutable singleton fields.

@ApplicationComponent
@Synchronized
class Counter {
    private var value: Int64 = 0
    fn increment() -> Int64 {
        this.value = this.value + 1
        return this.value
    }
}

@HttpRequestScoped
class Api {
    @Inject var counter: Counter
    @GET @Path("/count")
    fn count() -> Int64 { return this.counter.increment() }
}

@Synchronized on a non-generic application/startup class protects all instance methods; on an instance method it protects only that method. There is one recursive monitor per declaring class, shared by every annotated call and every instance of that class. Nested calls on the same thread are safe. Static methods are excluded from class-level synchronization; explicitly annotating a static method, generic method, unscoped class, interface/trait method or class with inheritance is rejected. This deliberately limited contract prevents silent gaps in generated locking.

The monitor is held across the method's defer/finally cleanup and transactional commit or rollback, and released before returning a result or error. Cancellation while waiting for a monitor throws without executing the body; cancellation inside it unwinds the body and releases the monitor. Existing errors are preserved during cleanup. Dev UI state snapshots use the class monitor when one is present.

Keep state private and protect reads as well as writes. Returned mutable objects, direct field access, static methods and unannotated methods bypass the monitor. Take snapshots inside a protected method instead of returning internal collections. Do not await a child that needs the monitor while holding it, and acquire different class monitors in a consistent order. Reentrancy applies to one thread, not spawned children. For smaller explicit critical sections, use tinox.core.semaphore locks with defer immediately after a successful acquisition; these native blocking locks do not become cancellable. Annotations and diagnostics do not prove universal race freedom.

HTTP Server (Low Level)

The HTTP server in the runtime uses:

• SO_REUSEPORT Multiple threads bind the same port – the kernel distributes connections
• epoll Event multiplexing: one thread manages up to 4,096 simultaneous connections
• TCP_NODELAY Nagle algorithm disabled – immediate sending of small packets
• Keep-Alive HTTP/1.1 keep-alive, idle timeout 500ms

Type System

Primitive Types

s.chars() returns List<String> containing one Unicode scalar value per element. Use for ch in s.chars() to process complete UTF-8 characters. Combining marks and emoji sequences may span several elements: this does not normalize text or segment graphemes. Empty input yields an empty list; malformed UTF-8 aborts with its byte offset. Length, indexing, charAt, and direct string iteration retain their byte semantics. The operation takes O(bytes) time and allocates a list plus one short string per scalar value.

Composite Types

const numbers: List<Int64> = [1, 2, 3]                 // Array
const ages: Map<String, Int32> = @{"Alice" => 30}  // Map/Dictionary
const pair: (Int32, String) = (42, "hello")           // Tuple
const name: String? = null                             // Nullable
const fn add: fn(Int32, Int32) -> Int32 = |a, b| a + b // Function type

Generics

Tinox supports parametric polymorphism via monomorphization: a separate function is generated for each concrete type – like C++ templates or Rust. There is no runtime overhead from type erasure (as in Java).

fn max<T>(a: T, b: T) -> T
{
    if a > b { return a }
    return b
}

class Box<T>
{
    var value: T
}

Object Orientation

Tinox is a hybrid language – object-oriented with classes, inheritance, and interfaces, but procedural free functions and functional concepts (lambdas, higher-order functions) are also possible.

Classes

class Animal
{
    var name: String
    var age:  Int32

    fn speak() -> String        // instance method
    {
        return "..."
    }

    fnc create(name: String) -> Animal  // static method (fnc)
    {
        return Animal { name: name, age: 0 }
    }
}

class Dog extends Animal       // inheritance
{
    fn speak() -> String
    {
        return "Woof!"
    }
}

Interfaces & Polymorphism

interface Serializable
{
    fn serialize() -> String
}

class User implements Serializable
{
    var name: String

    fn serialize() -> String
    {
        return "User:" + this.name
    }
}

Interface dispatch is implemented via vtables – identical to C++ virtual functions. Every object that implements an interface receives a pointer to a table of function pointers.

Absence and recoverable errors

For new library APIs, use Option<T> for absence and Result<T> for expected failures. Import tinox.core.option and tinox.core.result. Some("") means present-empty; None means absent. Check isSome()/isNone() or choose an explicit fallback with unwrapOr(). Do not add a nullable T? alternative for the same lookup.

Result<T> retains its String error. Use isOk()/isErr() and getError(); preserve operation, target and cause without exposing secrets. Do not infer status from message contents. APIs needing stable error categories should use documented domain outcome fields. A generic typed-error Result and allocation changes are deferred.

Exceptions remain appropriate for documented precondition, programming and setup failures. Option.unwrap() on None throws "Option is None"; Result.unwrap() on Err throws the original error. Callback exceptions propagate through combinators. Use finally for cleanup on normal and exceptional exits.

The additive HTTP methods findHeader, findParam, findQuery and QueryString::find return Option<String>. Headers are case-insensitive; path/query names are case-sensitive. Queries keep raw values, the last duplicate, and present-empty bare keys. Existing String getters keep their empty fallback without deprecation warnings. Use a package version that provides the optional methods, or matching workspace sources. See the API inventory and migration guide for examples and legacy I/O limitations.

The current checkout also provides checked filesystem alternatives: Fs::tryReadFile, tryWriteFile, tryAppendFile, tryCopyFile, tryMoveFile and tryDeleteFile. Their IoResult<T> keeps status and payload together; failure() exposes operation, target, OS code and cause. An empty read is success; partial reads and failed flushes are failures. Migration and compatibility contracts.

ByteStream and Http1Stream provide bounded, deadline-aware TCP/TLS streaming with explicit ownership and cleanup. HTTP/1.1 streaming supports one Content-Length exchange; HTTP/2/3 body bridges preserve binary bytes but still buffer whole bodies. Binary and streaming contracts.

Keyword Overview

Annotations

The annotation system is one of the core strengths of Tinox. Annotations control the behavior of the compiler, the HTTP server, and future frameworks – similar to Java/Spring or Quarkus.

HTTP REST Annotations

Every parameter of a @GET/@POST/etc. handler needs exactly one binding annotation: @PathParam/@QueryParam bind by the parameter's own name to the same-named :name path segment or query string key, @PostParam deserializes the whole JSON request body, @HttpContext gives access to the request/ response. The return type decides the response mode: HttpContext means manual mode (the method builds ctx.response itself), any other type gets auto-serialized as JSON.

// Auto-serialize: the return value becomes the JSON response body
@GET
@Path("/users/:id")
@Produces(MediaType.APPLICATION_JSON)
@Auth("bearer")
fn getUser(@PathParam id: Int64) -> User { ... }

// Manual mode: dynamic status code (e.g. 404), @HttpContext + -> HttpContext
@GET
@Path("/users/:id")
fn getUserOrNotFound(@PathParam id: Int64, @HttpContext ctx: HttpContext) -> HttpContext
{
    // ... ctx.response.status(404).json(...) or ctx.response.json(...)
    return ctx
}

Migrating from the old REST API

Before this version, every handler implicitly got exactly one unannotated ctx: HttpContext parameter, return type Nothing, and had to read path/query parameters and the request body manually via ctx.request.getParam(...)/ctx.request.getQuery(...)/ Json::deserialize<T>(ctx.request.body). That shape no longer compiles — there is no backward compatibility, every parameter now needs one of the four binding annotations explicitly.

Serialization

@JsonSerializable
class User
{
    var id:   Int64

    @JsonField("first_name")   // Overrides the JSON key
    var firstName: String

    @Sensitive              // Output as "***" in logs
    var password: String

    @DoNotSerialize         // Excluded from JSON
    var internalToken: String
}

All Built-in Annotations

Current contracts: DI providers and request contexts, recursive request validation and HTTP-400 details.

Standard Library (tinox-core)

The standard library consists of over 55 modules written in Tinox itself. Import: import tinox.core.<module>

LSP – Basics

The Language Server Protocol (LSP) is an open protocol developed by Microsoft in 2016 that standardizes the communication between a language server (which understands the programming language) and an editor (which shows the user interface).

The Problem Before LSP

Previously, every IDE had to implement its own plugins for every language: Eclipse plugin for Java, VS Code plugin for Java, IntelliJ plugin for Java – all separate implementations of the same logic. With n languages and m editors, n × m integrations were created.

LSP Solution: n + m Instead of n × m

With LSP you write one language server, and every LSP-compatible editor uses it automatically. The language server communicates via JSON-RPC over stdio with the editor.

Editor (Eclipse, VS Code, Neovim …)
      │
      │  JSON-RPC via stdin/stdout
      ▼
Language Server (tinox-lsp Binary)
      │
      │  Analyzes .tnx files
      ▼
Lex → Parse → Typecheck → Responses to editor

Important LSP Methods

Tinox LSP Server

tinox-lsp is a complete LSP server implemented with tower-lsp 0.20 (Rust) and Tokio as asynchronous runtime.

Embedded Standard Library

All 26+ standard library modules are embedded directly into the LSP binary using include_str!(). The server requires no installation or configuration of file paths – it works immediately after copying the binary.

Import Resolution for Diagnostics

When a .tnx file is opened, the LSP server automatically resolves import declarations and loads the corresponding stdlib ASTs as prelude. This way Json.parse() or HttpContext are not marked as "undefined".

Dot Completion for Classes

When the user types Json.:

1. The editor sends textDocument/completion with the offset after the dot
2. The LSP extracts the dot chain (["Json"])
3. It checks whether Json is a variable (instance) or a class name
4. If class name: directly load the methods of Json from the registry
5. Static methods (fnc) are displayed with the hint fnc parse(...)

Technical Details

Eclipse Plugin

The Eclipse plugin tinox-eclipse connects the Eclipse IDE with the tinox-lsp language server via the LSP4E framework – the LSP client for Eclipse.

Features

Architecture

The plugin is an OSGi bundle that registers the .tnx file extension via plugin.xml and instructs LSP4E to start the tinox-lsp process when .tnx files are opened. Communication runs over stdin/stdout in JSON-RPC.

CLI Tools

The tinox binary is the central tool for all development tasks:

HTTP Server & Performance

The integrated HTTP server is optimized for maximum throughput at minimal latency. It uses technologies also employed in production-ready systems such as Nginx and Envoy.

epoll – Event Multiplexing

Instead of blocking a thread for each connection, the server registers all active connections in an epoll file descriptor. One epoll_wait() call delivers all connections that have readable data – in a single system call.

// Concept (simplified):
epoll_fd = epoll_create1(0)
// Register all active connections...
while (true)
{
    events = epoll_wait(epoll_fd, max_events, 50) // 50ms Timeout
    for event in events
    {
        if event.fd == server_socket { accept() }
        else { handle_request(event.fd) }
    }
}

SO_REUSEPORT – Kernel Load Balancing

With SO_REUSEPORT, multiple threads (or processes) can listen on the same port simultaneously. The Linux kernel automatically distributes incoming connections to available listeners – without locks, without bottlenecks.

Thread-Local Buffers

Each HTTP worker thread has its own static buffer for request data, response data, and JSON parsing. These buffers are never freed and are reused – this completely eliminates malloc/free in the critical request path.

Concurrency Budgets & Overload Handling

Worker and connection counts are bounded and container-aware. The effective CPU count is the smaller of the process's CPU affinity (taskset, cpuset) and the cgroup CPU quota (v1 and v2, e.g. docker run --cpus=1.5 gives 2), not the host's core count. Each limit can be overridden with an environment variable; a malformed value aborts startup. The effective values are printed in the startup banner (Limits: ...) and exported on /metrics together with open/peak/rejected counters.

Every setting can also be placed in application.properties as tinox.limits.<name> (e.g. tinox.limits.max_tasks=256); the environment variable wins. The Dev UI API exposes the effective values and live counters at /limits. HTTP/1 rejects immediately (the epoll workers must not block); the HTTP/2, HTTP/3 and TLS accept loops are single-threaded by design, so their backlog is bounded by the kernel listen queue and they never grow threads. AMQP connections use spawn and therefore count against TINOX_MAX_TASKS. A rejected request is never retried automatically. Bind address: by default every listener (HttpServer, @TinoxUIApp, WebSocket, HTTP/2, SSE) binds 0.0.0.0. TINOX_BIND_ADDRESS=127.0.0.1 restricts them to one IPv4 address (e.g. loopback-only for local dashboards); an invalid value aborts startup.

Benchmark: Tinox vs. Quarkus

A sort REST endpoint was measured under identical conditions against Quarkus (Java, native image):

Test conditions: 5,000 requests, concurrency 20, list with 20 numbers per request, Linux x86_64.

Pros & Cons

Comparison: Memory Safety

Tinox gives the developer full control over memory – like C –, but does not offer static guarantees like Rust's borrow checker. This means:

Use Cases

Less Suitable For…

• Frontend development (no browser target, no WASM focus)
• Data science / ML (no NumPy equivalent, no notebook integration)
• Mobile apps (no iOS/Android framework)
• Projects that require a huge package ecosystem (npm, Maven)

Comparison with Other Languages

ORM & Lambda Query DSL

Tinox provides a type-safe ORM inspired by JPA/QueryDSL. Classes are annotated as database tables, and all queries run through a type-safe lambda DSL — no string-based queries.

Annotations

Entity Definition

@Entity
@Table("users")
class User {
    @Id @GeneratedValue
    var id: Int64
    @Column("name")
    var name: String
    @Column("age")
    var age: Int64
    @Column("active")
    var active: Bool
}

tinox.toml – [database] Configuration

# PostgreSQL
[database]
driver = "postgres"
url    = "postgres://user:pass@localhost:5432/mydb"
pool   = 10

# MySQL / MariaDB
[database]
driver = "mysql"
url    = "mysql://user:pass@localhost:3306/mydb"

# SQLite (no DB server required)
[database]
driver = "sqlite"
url    = "sqlite:///path/to/database.db"

Lambda Query DSL

// All users over 18, sorted alphabetically, max 10 results
const adults: List<User> = DB::of(User)
    .filter(u -> u.age > 18)
    .orderBy(u -> u.name)
    .limit(10)
    .list()

// Read a single user
const alice: User = DB::of(User)
    .filter(u -> u.name == "Alice")
    .first()

// Count active users
const n: Int64 = DB::of(User)
    .filter(u -> u.active == true)
    .count()

Lambda → SQL Translation Table

Save, Update, Delete

// INSERT (ID assigned by the DB)
const user: User = User {}
user.name = "Alice"
user.age  = 30
const saved: User = DB::of(User).save(user)

// DELETE
DB::of(User).delete(saved)

// Save multiple entities
const list: List<User> = List::new()
list.add(user1)
list.add(user2)
DB::of(User).saveAll(list)

Error Handling

Database errors are currently logged to stderr. Integration with try/catch is planned for a future release. Connection errors at startup terminate the program with a descriptive message.