Glossary

Key terms and concepts of the Yuneta framework, sorted alphabetically.

Action callback

Function executed when an event fires in a given FSM state. Signature: int (*)(hgobj gobj, gobj_event_t event, json_t *kw, hgobj src). See GClass guide.

Append-only log

Timeranger2’s fundamental storage model — records are only appended, never overwritten. Each record gets a monotonically increasing g_rowid. See Timeranger2 guide.

Attribute

A typed property of a gobj, defined in the GClass attrs_table via SData descriptors. Attributes have a type, access flags, default value, and description. See Attributes API.

Authentication

Verification of a user’s identity through credentials (JWT tokens, user/password). See Authorization guide.

Authorization

Access control that determines whether an authenticated user can perform a specific action. Defined per GClass in the authz_table. See Authorization guide.

Bottom gobj

A designated child gobj that shares attributes and forwards events with its parent — Yuneta’s alternative to class inheritance. See Basic concepts.

Command

A named operation exposed by a gobj’s command_table, executable from the control plane regardless of FSM state. See Command parser guide.

Composition

Yuneta’s object-reuse pattern: behavior is assembled by nesting gobjs (parent → child → bottom) and routing events between them, instead of using class inheritance.

Control plane

The built-in mechanism that exposes every yuno’s commands and stats over a local socket or WebSocket. Interact with it using ycommand, ybatch, or ystats. See Utilities.

CRUDLU

Extended CRUD operations for TreeDB: Create, Read, Update, Delete, Link, Unlink — accounting for graph relationships between nodes.

Event

A typed message (event name + JSON kw payload) sent between gobjs via gobj_send_event(). Events are the only way gobjs communicate. See Events & State API.

Event-driven architecture

Yuneta’s core design: nothing happens without an event. The yev_loop processes I/O, timers, and signals, then propagates them as gobj events.

Fkey (Foreign Key)

A field on a child TreeDB node that stores a persistent reference to its parent, encoded as "topic^parent_id^hook_name". Link/unlink operations save only the child’s fkey.

FSM (Finite State Machine)

The mechanism that governs a gobj’s behavior: a set of states, valid events per state, action callbacks, and state transitions. Every gobj has one. See GClass guide.

GClass (GObject Class)

A blueprint defining the structure and behavior of gobjs: FSM (states + events), attributes, commands, authorization rules, and lifecycle methods (GMethods). See GClass guide.

GMethod

A lifecycle or behavioral callback in the GClass GMETHODS table (mt_create, mt_destroy, mt_start, mt_stop, mt_play and mt_pause). See GClass guide.

gobj (GObject)

A runtime instance of a GClass: a modular, event-driven component with its own FSM, attributes, and position in the gobj tree. See Basic concepts.

g_rowid

Global record identifier in timeranger2 — monotonically increasing counter for a given key within a topic. Never resets.

GBuffer (gbuffer_t)

Growable byte buffer used for binary I/O throughout the framework. See GBuffer guide.

hgobj

Opaque handle to a gobj instance (typedef void *hgobj).

hgclass

Opaque handle to a registered GClass (typedef void *hgclass).

Hook

A field on a parent TreeDB node that references child nodes. Hooks are in-memory relationships — persistence is through the child’s fkey.

Horizontal scaling

Yuneta’s scaling strategy: run one yuno per CPU core and communicate via inter-event messaging. No threads, no locks.

i_rowid

Row index within a key’s md2 file in timeranger2 — monotonically increasing per key.

Inter-event messaging

RPC-like communication between yunos over the network. A local gobj subscribes to a remote service as if it were local. See Inter-Event GClasses and Messaging API.

io_uring

Modern Linux asynchronous I/O interface used by yev_loop for all non-blocking operations (sockets, timers, signals, filesystem). See liburing, the userspace library Yuneta links against.

JSON

The only data format in Yuneta — used for events, messages, logs, stats, configuration, and persistence. All payloads are json_t * objects (Jansson library).

kw (keyword arguments)

A json_t * JSON object carrying the data payload of an event or command. Ownership semantics (owned/not-owned) are indicated in function signatures.

kwid

Library for advanced JSON manipulation: path-based access, filtering, cloning, matching, and comparison of JSON structures. See kwid guide and kwid API.

LMethod (Local Method)

A private method on a GClass, invoked explicitly via gobj_local_method() — not part of the FSM dispatch.

Node

A JSON object in TreeDB identified by a primary key (id). Contains __md_treedb__ metadata with g_rowid, i_rowid and topic_name.

Parent / Child

Gobjs form a hierarchical tree. Every gobj has exactly one parent (except the root yuno). Parents create and manage their children.

Persistent attribute

An attribute with the SDF_PERSIST flag — automatically saved to and loaded from disk. See Persistent attrs guide.

Pkey (Primary key)

The column that addresses a record in a topic. In TreeDB it is always id, and always a string. A create carries it, unless the column declares uuid, rowid or qualified — the three flags that make the topic hand the key out. A column carries at most one of the three. See the TreeDB crash course §3.3.

Publish / Subscribe

Pattern where a gobj publishes output events to all subscribed gobjs via gobj_publish_event() / gobj_subscribe_event(). See Publish API.

Pure child

A gobj created with gobj_flag_pure_child — sends events directly to its parent without requiring explicit subscriptions.

Qualified id

A pkey flag: a create that sends no id gets the id of its parent, a dot, and its own name. The name is the first secondary key of the topic (pkey2s). The parent is the one named in the fkey of the create. The id is unique by construction, because a name is unique inside its parent. The separator cannot be ^, the character an fkey reference is split on. treedb_system_schema keys its topics and cols this way. See the TreeDB crash course §3.11.

Realm

A running yuno or a logically grouped set of yunos, identified by Role, Name, and Owner.

Re-launch (Watcher-Worker)

Yuneta’s self-healing daemon mechanism. In daemon mode, a watcher process monitors the worker (the actual yuno) and re-launches it after a crash or a non-zero exit. It does not re-launch after a clean exit(0) or after SIGKILL — both mean “stay down”, which is how the agent kills yunos. No systemd required. See Watcher signal posture.

Rowid key

A pkey flag: a create that sends no id gets the size of the topic plus one. It is not g_rowid or i_rowid, which timeranger2 gives to every record — this one is the address of a node. The address is unique but arbitrary: it does not reproduce, and a rowid pkey has no update, so an editor that saves a record appends a second one instead of changing the first. It is here for the stores that already use it. Do not declare it in a new topic.

SData (Structured Data)

The schema system used to define typed fields with metadata (type, flags, default, description) for attributes, commands, and database records. See SData guide.

Service

A gobj registered with gobj_create_service() that exposes commands and events for external interaction. Found by name via gobj_find_service().

Single-threaded

Every yuno runs in a single thread — no locks, no mutexes. CPU-bound work blocks the entire event loop. Scale horizontally instead.

Snapshot

A point-in-time capture of TreeDB state for backup/restore. Managed via treedb_shoot_snap() / treedb_activate_snap().

State

A named stage in a gobj’s FSM. Predefined states: ST_STOPPED, ST_IDLE, ST_DISCONNECTED, ST_CONNECTED, ST_OPENED, ST_CLOSED.

Stats

Operational metrics exposed by every gobj (byte counters, message rates, connection counts). Attributes flagged SDF_STATS or SDF_RSTATS. Query with gobj_stats() or ystats.

Subscriber

A gobj that has subscribed to receive published events from another gobj.

Timeranger2

Append-only time-series storage engine — the persistence primitive underlying TreeDB, queues, and message stores. See Timeranger2 guide and Timeranger2 API.

Topic

A collection of records in timeranger2, organized by key with time-based indexing.

Trace level

A runtime diagnostic category that can be dynamically enabled/disabled per gobj or GClass. Defined in s_user_trace_level and controlled via the control plane.

TreeDB (tr_treedb)

Graph memory database built on timeranger2. Nodes belong to topics and are linked via hook/fkey relationships. See TreeDB API.

UUID key

A pkey flag: a create that sends no id gets a random UUID. The address is unique everywhere and means nothing to a person. A reader that must NAME such a record reads the secondary key (pkey2s) that the topic descriptor carries.

yev_loop

The event loop engine — drives all asynchronous I/O using Linux io_uring. Manages sockets, timers, signals, and filesystem events. See Event Loop guide and Event Loop API.

Yuno

A deployable, single-threaded process composed of a hierarchical tree of gobjs. The root gobj is always a C_YUNO. See Basic concepts.