JS: GClass Registration

GClass Registration¶

A gclass is a definition that the application registers one time at start up. It carries the schema of the attributes, the finite state machine, the methods of the lifecycle, the commands and the authorizations.

Source code: src/gobj.js

GObj¶

The class of an instance. is_gobj() tells if a value is one. Application code does not build one with new. It calls a creation function of the lifecycle.

gclass_create()¶

Registers a gclass.

gclass_create(
    gclass_name,        // "C_MY_CLASS"
    event_types,        // [[event_name, flag], …]
    states,             // [[state_name, ev_action_table], …]
    gmt,                // the methods of the gclass (mt_create, mt_start, …)
    lmt,                // the local methods
    attrs_table,        // the array of SDATA
    priv,               // the private data, copied for each instance
    authz_table,        // or 0
    command_table,      // or 0
    s_user_trace_level,
    gclass_flag
)

Returns

The gclass, or null when the registration fails.

gclass_flag_t¶

The flags of a gclass.

gclass_find_by_name(gclass_name, verbose)¶

Finds a gclass by its name. With verbose set to true the function writes a log error when the gclass does not exist.

gclass_unregister(gclass)¶

Takes a gclass out of the register. It accepts the gclass or its name.

gclass_check_fsm(gclass)¶

Checks the finite state machine of a gclass, and gives the quantity of the errors that it finds. It finds an action that goes to a state that does not exist, and an event that no state declares.

Build a gclass at run time¶

These four functions build a gclass one piece at a time. Application code rarely needs them. A generator of code and a dynamic gclass use them.

gclass_add_state(gclass, state_name)¶

Adds one state.

gclass_add_ev_action(gclass, state_name, event_name, action, next_state)¶

Adds one row of (event, action, next state) to a state.

gclass_add_event_type(gclass, event_name, event_flag)¶

Adds one event to the list of the events of the gclass.

gclass_event_type(gclass, event_name)¶

Gives the record of an event of the gclass, with its flags.

The action function¶

function ac_connect(gobj, event, kw, src) {
    // event = "EV_CONNECT"
    // kw    = the JSON payload, such as { url: "ws://…" }
    // src   = the gobj that sent the event
    //
    // Give 0 back on success, and -1 on failure.
    return 0;
}

See Writing a Custom GClass for a full example.

The subscription model¶

Each gclass takes one of two models, and writes the block in mt_create. Do not invent a third one.

/*
 *  CHILD subscription model
 */
let subscriber = gobj_read_pointer_attr(gobj, "subscriber");
if(!subscriber) {
    subscriber = gobj_parent(gobj);
}
gobj_subscribe_event(gobj, null, {}, subscriber);

/*
 *  SERVICE subscription model
 */
const subscriber = gobj_read_pointer_attr(gobj, "subscriber");
if(subscriber) {
    gobj_subscribe_event(gobj, null, {}, subscriber);
}

A child goes to its parent, and the parent declares every event that the child publishes. A service goes to the subscribers that ask for it.

When a publication of a child gives “Event NOT DEFINED in state”, add the event to the state machine of the parent, or make the gobj a service. Never take the parent out of the child model to make the message quiet.