Skip to article frontmatterSkip to article content
Site not loading correctly?

This may be due to an incorrect BASE_URL configuration. See the MyST Documentation for reference.

GClass

What is a GClass?

A GClass (short for GObject Class) is a core construct in the Yuneta framework. It defines the behavior, attributes, and structure of GObjects (runtime instances of a GClass). The GClass encapsulates the functionality and state machine of a particular object type, serving as a blueprint for creating and managing GObjects.

A GClass in Yuneta is the foundation for defining the behavior and structure of objects in the framework. It encapsulates attributes, methods, and finite state machines, enabling the creation of reusable, modular, and extensible components.

Source code in:

Components of a GClass

A GClass consists of several key components that define its operation:

  1. GClass Name

    • Unique name to identify it.

  2. Attributes

    • Set of public attributes

  3. Private Variables

    • Set of private variables

  4. Global Methods

    • Set of global methods that supports

  5. Local Methods

    • Set of local methods that supports

  6. Event Table

    • Set of public and private events.

  7. State Table

    • Set of states with event/actions

  8. Authorization Table

    • Specifies access control rules.

  9. Command Table

    • Describes executable commands for the GClass.

  10. Trace Levels

    • Defines trace levels for debugging and monitoring.

  11. gclass_flag

    • Modifier of behavior

How a GClass Works

  1. Definition:

    • A GClass is created using the gclass_create() function, combining its attributes, methods, states, events, and other metadata.

  2. Instantiation:

    • A GObject instance is created from a GClass using the GObject API.

  3. Interaction:

  4. Extensibility:

    • The modular design of GClass allows new behaviors and features to be added by defining additional methods, events, or states.

gclass_name_t

The name of the gclass.

Each GClass has a unique name to identify it.

In C must be defined with the macro GOBJ_DEFINE_GCLASS in .c file and GOBJ_DECLARE_GCLASS in .h file.

Attributes

Attributes in a GClass define its properties or state. They are represented as structured data of type sdata_desc_t in the attrs_table table, where each entry describes an attribute’s type, access flags, default value, and purpose. Attributes are the foundation of a GClass, providing a schema for configuration, runtime state, and operational behavior.

Key Features of Attributes

1. Data Types

Attributes support various data types, enabling them to store different kinds of information. Common data types include:

2. Flags

Flags define the access permissions and characteristics of attributes:

3. Default Values

Default values ensure that attributes are initialized with predictable and meaningful data. They are applied when no explicit value is provided during configuration or runtime.

4. Descriptions

Each attribute includes a description that explains its purpose and behavior. Descriptions serve as documentation for developers and users interacting with the GClass.

5. Hierarchical Definitions

Attributes can reference other schemas, allowing for nested and hierarchical data structures. This capability enables complex configurations while maintaining clarity.

Purpose of attrs_table

The attrs_table table serves multiple purposes in a GClass:

High-Level Overview of Attributes

ComponentDescription
TypeSpecifies the data type of the attribute (e.g., string, boolean, integer).
NameThe unique identifier for the attribute.
FlagsDefine access permissions and additional properties (e.g., read-only, persist).
Default ValueThe initial value of the attribute if none is provided.
DescriptionExplains the purpose and behavior of the attribute.

Examples of Common Attribute Use Cases

1. Runtime Statistics

Attributes can store real-time statistical data, such as:

These attributes often use flags like SDF_RD (read-only) and SDF_RSTATS (resettable statistics).

2. Configuration Settings

Attributes can define configurable properties, such as:

3. Environment Metadata

Attributes can represent metadata about the GClass or its environment, including:

Benefits of Attribute Design with attrs_table

Finite State Machine

In Yuneta, gobj_state_t and gobj_event_t define the behavior of GObj finite state machines (FSM). This event-driven architecture allows for structured and predictable execution.

gobj_state_t

GObj states represent different stages in an object’s lifecycle, defining how it behaves and responds to events. Each state is identified by a unique name and is used to manage transitions between different operational conditions.

Unique pointer that exposes state names, defined as:

In C:

typedef const char *gobj_state_t;

gobj_event_t

GObj events represent actions or signals that trigger transitions between states, facilitating communication between objects. Each event has a specific meaning within the system and determines how a GObj responds to changes or external inputs.

Unique pointer that exposes event names, defined as:

In C:

typedef const char *gobj_event_t;

The FSM ensures clear behavior and modular event handling.

🛠️ How It Works

State Machine Structure

Each GObj has a state table mapping events to actions:

Event Handling

When an event occurs, the FSM:

  1. Checks the current state.

  2. Finds the event in the state table.

  3. Executes the associated action.

  4. Moves to the next_state if defined.

Predefined States and Events in the System

Predefined States (gobj_state_t)

The following states are defined in the system using GOBJ_DEFINE_STATE():

Predefined Events (gobj_event_t)

The following events are defined in the system using GOBJ_DEFINE_EVENT():

These events represent system signals for timeouts, state transitions, messaging, connection handling, and data transmission. They are used to trigger actions within the system, allowing GObjs to react to external stimuli, manage their internal state, and facilitate communication between different components.

These predefined states and events form the core of Yuneta’s GObj framework, enabling structured event-driven programming and state management. States define the behavior of an object at any given time, while events act as triggers that drive transitions between these states. Together, they create a dynamic and responsive system that efficiently handles various operational scenarios.

Is a system event. Publish when a FSM change his state.

Private Attributes

GMETHODS

The GMETHODS structure in Yuneta defines the global methods that a GClass can implement. These methods encapsulate key behaviors and operations associated with the lifecycle, state management, and functionality of GObjects.

Each method serves a specific purpose and is invoked through the GObject API, enabling dynamic and modular behavior across different GClasses.

The GMETHODS structure enables flexible, modular behavior in the Yuneta framework. Each method is optional, allowing GClasses to implement only the functionality they need.

Methods

Mapping

This section maps GObject API functions to the GMETHODS they invoke. It provides a detailed overview of how GMETHODS are utilized within the GObject lifecycle.

This mapping provides a detailed and structured view of how GMETHODS are utilized across various GObject API functions, covering attributes, events, TreeDB, lifecycle, and more. Each method plays a specific role in the modular design of the GClass.

Creation and Destruction

Attribute Management

Lifecycle Management

Event and State Management

Subscription Management

Resource Management

Publishing Events

Commands and Statistics

Authorization

TreeDB Management

Snapshots

Tracing

LMETHOD

The LMETHOD structure in the Yuneta framework defines the local methods that can be implemented by a GClass. These methods are specific to the internal operation of the GClass and are not intended to be invoked dynamically via the gobj_local_method() API, unlike the global methods (GMETHODS).

Event Table

In C:

typedef struct event_type_s {
    gobj_event_t event;
    event_flag_t event_flag;
} event_type_t;

States Table

Defines the behavior of the GClass in terms of states, events, and transitions: - States: Predefined states (e.g., ST_CLOSED, ST_OPENED). - Events: Triggers for state transitions (e.g., EV_ON_OPEN, EV_ON_CLOSE). - Actions: Functions executed during transitions between states.

In C:

typedef struct states_s {
    gobj_state_t state_name;
    ev_action_t *state;
} states_t;

Authorizations

The authz_table in a GClass defines the permissions required to access specific operations or resources. Each entry in the authz_table describes a distinct authorization, including its parameters, description, and validation schema. The authz_table is implemented using sdata_desc_t structures.

Key Features of Authorizations

1. Authorization Levels

Each authorization defines a level or type of access, such as:

2. Validation Parameters

Each authorization level can specify a schema that describes the parameters required for validation. For example:

3. Authorization Paths

Authorization paths define the logic for validating access. Paths may:

4. Descriptions

Each authorization includes a description that clearly defines its purpose. These descriptions serve as documentation and help developers and administrators understand the access requirements.

Purpose of authz_table

The authz_table enforces access control within a GClass. By defining and validating authorizations, the GClass ensures that operations are performed only by users or systems with the necessary permissions.

Validation of Authorizations

The authz_table works with APIs like gobj_user_has_authz to validate permissions dynamically. These APIs:

  1. Check if the current user or system has the required authorization.

  2. Validate the input parameters against the schema defined for the authorization.

  3. Respond with an appropriate error or success message.

High-Level Process

  1. Permission Check: Specify the desired permission (e.g., "create").

  2. Validation: The gobj_user_has_authz function validates the authorization based on:

  1. Action Execution: If the validation passes, the requested action is performed. Otherwise, an error is returned.

Benefits of authz_table

Example Use Cases

Authorization Levels

Parameterized Authorizations

Command Table

The command_table in a GClass defines the available commands and their corresponding behaviors. Each command is represented as an entry in the table, described with parameters, aliases, execution logic, and a human-readable description. This structured approach ensures consistency, flexibility, and clarity in how commands are defined and executed.

Key Features of Commands

1. Command Names

Each command is identified by a unique name, which is used to invoke the command programmatically. For example:

2. Aliases

Commands can have alternative names (aliases) to provide flexibility and improve usability. For instance:

3. Parameters

Commands accept structured input, described using schemas. These schemas are defined in sdata_desc_t tables, specifying:

4. Handlers

Each command is linked to a function that implements its logic. These handler functions:

5. Descriptions

Commands include a detailed description to document their purpose and functionality. This description is useful for both users and developers.

Purpose of command_table

The command_table serves as a central registry for all commands available in a GClass. It provides:

High-Level Overview of Command Definitions

ComponentDescription
Command NameThe unique identifier for the command.
AliasesAlternative names for the command, improving usability.
ParametersInput schema defining the required and optional parameters for the command.
Handler FunctionA function that implements the command’s logic.
DescriptionDocumentation describing the command’s purpose and behavior.

Benefits of command_table

Trace Levels

Trace levels allow precise control over debugging and diagnostic logging in a GClass. By defining a table of trace levels (s_user_trace_level), GClasses can manage which aspects of their behavior are logged, ensuring detailed, yet efficient, monitoring and debugging.

In C:

typedef struct {
    const char *name;
    const char *description;
} trace_level_t;

Key Concepts

Trace Level Table (s_user_trace_level)

The trace level table defines all available trace levels for a GClass. Each entry in the table includes:

Managing Trace Levels with GObj API

Trace levels are dynamically managed using the GObj API. These functions allow for:

Core API Functions

1. Listing Trace Levels

Retrieve the list of all defined trace levels for a GClass:

2. Retrieving Active Trace Levels

Retrieve the currently active trace levels at various scopes:

3. Tree and Hierarchy Retrieval

Retrieve trace levels across hierarchical scopes:

4. Querying and Checking Trace Levels

Query specific trace levels for a GObj instance:

5. Setting Trace Levels

Enable or disable trace levels dynamically at different scopes:

6. Deep Tracing

Deep tracing enables comprehensive logging across all levels:

Practical Use Cases

1. Dynamic Logging

During runtime, trace levels can be toggled on or off to focus on specific areas, such as:

This dynamic control reduces log clutter and enhances debugging efficiency.

2. Debugging Hierarchies

Trace levels can propagate across GClass and GObj hierarchies. For instance:

3. Selective Analysis

Trace levels allow selective analysis of specific features or operations, improving troubleshooting accuracy. For example:

Benefits of Trace Levels

gclass_flag_t

The gclass_flag_t enumeration defines flags that can be applied to a GClass to modify its behavior. These flags are used to control specific operational aspects of the GClass.

Values of gclass_flag_t Flags

global_list_persistent_attrs_fn

TODO
Guides
Basic Concepts
Guides
GObj