Programming API

  1. Functions
  2. Logs

Functions

The xGraph platform offers a number of features to support the development of these fractal graph architectures. In addition to the self-similar architecture defined by entities and modules, xGraph’s Nexus provides programmers with a few special functions. These functions provide programmers with the ability to communicate between entities and modules (or build relations), generate xGraph structures dynamically, and save the current state of a system. All these functions exist in the this context of every entity.

this.genModule(moduleObject, callback);

-and-

this.genModules(moduleObject, callback);

The genModule function takes a module object and a callback function, starts the modules found in the module object, and then calls the callback function.

The module object can be: Either a single module definition object

{
	Module: "xGraph.Proxy",
	Source: "Core",
	Par: {
		Role: "Client",
		Host: "127.0.0.1",
		Port: 25005,
		Poll: true
	}
}

Or an object of module definitions with descriptive keys

{
        "Plexus": {
            "Module": "xGraph.Plexus",
            "Source": "xGraph",
            "Par": {}
        },
        "Proxy": {
            "Module": "xGraph.Proxy",
            "Source": "xGraph",
            "Par": {
                "Link": "$Plexus",
                "Role": "Server"
            }
        }
    }

this.addModule(moduleName, moduleZip, callback);

The addModule function allows you to add a module to the system by adding the module’s zip to the system’s cache. To use this function, the --allow-add-module flag must be set when running the system from the CLI. addModule takes the Zipped module file and inserts it into the system’s cache under the name of the module.

this.genEntity(entityDefinition, callback);

The genEntity command takes an entity definition object and generates the entity in the module. An entity can only be generated in the module that is making the call. When the function is complete, the callback is returned with the pid of the generated entity in object.Pid.

The entity definition must have an "Entity" key valued with the name of the entity being generated. The entity must exists in the same module as the entity that is calling genEntity. For more information on defining entities, see our Entity Guide.

Here is an example of an entity being generated. The Suite.js entity is generated with a Setup and Start command and no parameters.

let entity = {
	"Entity": "Suite.js",
	"$Setup": "SetupCommand",
	"$Start": "StartCommand"
};


let callback = ((err, apx) => {
	this.Vlt.gennedEntity = com.Pid = apx;
	fun(null, com);
});

this.genEntity(entity, callback);

this.deleteEntity(apex, pid, callback);

The deleteEntity function takes a module apex, an entity pid and a callback function and deletes the entity from the module’s memory. If the entity pid is the module’s apex, then all the module’s entities are deleted.

this.genPid();

The genPid function does not accept any parameters and returns a 32 character hexadecimal pid.

this.send(command, pid, callback);

The special function that you will use most is the send function. send requires three parameters: a command object, a destination pid, and a callback function. Send then sends the command object and the callback function to the xGraph part (entity or module, depending on the fractal layer) specified in the Pid.

The command object must have a Cmd key valued as the command that is being sent. The simplest commands look like this:

{
    "Cmd": "Ping"
}

Additionally, the command object is used to pass information from one node to another. Any number of key-value pairs can be added to the command object to handle information exchange. Here is a command with multiple parameters:

{ 
    Cmd: "Subscribe", 
    Pid: this.Par.Pid, 
    Link: "2DView" 
}

Pids are generated by Genesis when and xGraph system is compiled, and saved in references, typically in the this.Par object. These references are defined in a system’s structure object, typically a config.json file, or a module’s structure object, a schema.json file.

Here is an example of a command being sent to a Pid referenced in the entities parameter object, this.Par, and then calling a callback function.

    var commandObject = {
        Cmd: "OtherFunction",
        someValue: 1
    };

    that.send(commandObject, that.Par.Friend, callback);

    function callback(err,com){
        log.i("----Recieved callback from Other, someValue is now: ", com.someValue);
        commandObject.someValue = com.someValue;
        log.i("--xGraph Repeats: [" + message.toString().trim() + "]");
        log.i("HelloWorld is Listening... Type Something!");
    }

this.save(callback);

The save function takes only a callback function. The function saves the state of this entity, the entity that called the function, including its current Par and Vlt, to the cache. If this entity is not an Apex, the save message is sent to the Apex of this entity’s module. If it is an Apex, save the entity’s information, as well as all other relevant information. When this is complete, the callback function is called.

You can use this.send() anytime to save an entity by simply using this.send(callback); Here is an example of an entity that saves itself on the Start command:

	function Start(com, fun) {
		console.log('--Model/Start');
		this.save();
		if(fun)
			fun();
	}

this.getFile(module, filename, callback);

Get a file from the module.json module definition.

this.require(‘module’);

The require function handles external dependencies in xGraph. Given a module name, require loads the given module, returning the module object. Often, you will want to save the module object in the entity’s Vault, this.Vlt.

Here, we load the sqlite3 dependency, check to see that it loaded properly, and then save sqlite3 module to this.Vlt with the key Sqlite3.

let sqlite3 = this.require('sqlite3');

if (sqlite3 == null || sqlite3 == undefined) {
     errors = "Unable to load sqlite3.";
}


Vlt.Sqlite3 = sqlite3;

this.exit(code);

The exit function instructs nexus to exit with the code provided. Nexus will then stop all running xGraph processes related to the system.

Logs

xGraph offers a suit of logging functions that enable logs to be printed or saved without losing information on the structure of your xGraph system. There are a variety of functions available to print logs, each with its own special functionality. Next we will look at the different log functions and how they might be used.

Info - log.i(string);

log.i takes a string and prints it. It is meant for printing general statements and logs. These will be printed and will be printed in turquoise.

Warning - log.w(string);

log.w takes a string and prints it. It is meant for printing warning statements and logs. These will typically be printed in white.

Error - log.e(string);

log.e takes a string and prints it. It is meant for printing error statements and logs. These will typically be printed in red.

Debug - log.d(string);

log.d takes a string and prints it. It is meant for printing debug statements and logs. These will typically be printed in fuchsia.

Verbose - log.v(string);

log.v takes a string and prints it. It is meant for printing verbose statements, or statements that give specific or detailed information. These will typically be printed in gray.