namespace colonio #

All the functions of colonio are defined in the colonio namespace.

enum ErrorCode #

ErrorCode is assigned each error reason and is used with Error and Exception.

See also: Error, Exception

class colonio::Colonio #

Main class of colonio. One instance is equivalent to one node.

virtual ~Colonio() #

Destroy the Colonio object.

Run disconnect if necessary.

See also: disconnect()

void connect(const std::string & url,const std::string & token) #

Connect to seed and join the cluster.

Parameters #

• url Set the URL of the seed. e.g. “wss://host:1234/path”.
• token token does not use. This is an argument for future expansion.

Connect to the seed. Also, if there are already other nodes forming a cluster, join them. This method works synchronously and waits for the connection to the cluster to be established. If this method is successful, it will automatically reconnect until disconnect will be called. If you want to work asynchronously, use a asynchronous connect method instead. This method throws Error when an error occurs. At successful completion, nothing is returned.

See also: Colonio::connect(const std::string& url, const std::string& token, std::Exec<void(Colonio&)>&& on_success, std::function<void(Colonio&, const Error&)>&& on_failure)

void connect(const std::string & url,const std::string & token,std::function< void(Colonio &)> && on_success,std::function< void(Colonio &, const Error &)> && on_failure) #

Connect to seed and join the cluster asynchronously.

Parameters #

• url Set the URL of the seed. e.g. “wss://host:1234/path”.
• token token does not use. This is an argument for future expansion.
• on_success The function will call when success to connect.
• on_failure The function will call when failure to connect with error information.

The main purpose of the function is the same as connect(const std::string& url, const std::string& token). This method works asynchronously, and the method returns immediately. Note that the specified callback function is called in a separate thread for processing.

See also: connect(const std::string& url, const std::string& token)

void disconnect() #

Disconnect from the cluster and the seed.

This method works synchronously, it will wait for disconnecting and finish thread to process. This method must not be used in any other callback in colonio because of stopping the thread and releasing resources. Once a disconnected colonio instance is reused, it is not guaranteed to work. This method throws Error when an error occurs. At successful completion, nothing is returned.

void disconnect(std::function< void(Colonio &)> && on_success,std::function< void(Colonio &, const Error &)> && on_failure) #

bool is_connected() #

std::string get_local_nid() #

Get the node-id of this node.

The node-id is unique in the cluster. A new ID will be assigned to the node when connect. Return an empty string if node-id isn’t assigned.

Returns #

std::string The node-id of this node.

std::tuple< double, double > set_position(double x,double y) #

Sets the current position of the node.

This method is only available if the coordinate system is enabled. The coordinate system depends on the settings in seed. This method works synchronously, but other nodes know the position of this node asynchronously.

Parameters #

• x Horizontal coordinate.
• y Vertical coordinate.

Returns #

std::tuple<double, double> The rounded coordinates will be returned to the input coordinates.

Value messaging_post(const std::string & dst_nid,const std::string & name,const Value & message,uint32_t opt) #

Post a message for the destination node and wait response message.

This method provides the simple feature like RPC.

Parameters #

• dst_nid Target node’s ID.
• name
• message
• opt Options.

void messaging_post(const std::string & dst_nid,const std::string & name,const Value & message,uint32_t opt,std::function< void(Colonio &, const Value &)> && on_response,std::function< void(Colonio &, const Error &)> && on_failure) #

Post a message for the destination node and get response message asynchronously.

Parameters #

• dst_nid Target node’s ID.
• name
• message
• opt Options.
• on_response A callback will be called when get response message.
• on_failure A callback will be called when an error occurred.

void messaging_set_handler(const std::string & name,std::function< void(Colonio &, const MessagingRequest &, std::shared_ptr< MessagingResponseWriter >)> && handler) #

register the handler for

If another handler has already been registered, the old one will be overwritten.

Parameters #

• name A name to identify the handler.
• handler The handler function. null if the received message does not require response.

void messaging_unset_handler(const std::string & name) #

Release the function registered in the on_call method.

Parameters #

• name A name to identify the handler.

std::shared_ptr< std::map< std::string, Value > > kvs_get_local_data() #

void kvs_get_local_data(std::function< void(Colonio &, std::shared_ptr< std::map< std::string, Value »)> handler) #

Value kvs_get(const std::string & key) #

void kvs_get(const std::string & key,std::function< void(Colonio &, const Value &)> && on_success,std::function< void(Colonio &, const Error &)> && on_failure) #

void kvs_set(const std::string & key,const Value & value,uint32_t opt) #

void kvs_set(const std::string & key,const Value & value,uint32_t opt,std::function< void(Colonio &)> && on_success,std::function< void(Colonio &, const Error &)> && on_failure) #

void spread_post(double x,double y,double r,const std::string & name,const Value & message,uint32_t opt) #

void spread_post(double x,double y,double r,const std::string & name,const Value & message,uint32_t opt,std::function< void(Colonio &)> && on_success,std::function< void(Colonio &, const Error &)> && on_failure) #

void spread_set_handler(const std::string & name,std::function< void(Colonio &, const SpreadRequest &)> && handler) #

void spread_unset_handler(const std::string & name) #

protected Colonio() #

Construct a new Colonio object.

class colonio::ColonioConfig #

bool disable_callback_thread #

disable_callback_thread is a switch to disable creating new threads for exec callback.

The callback functions are exec on Colonio’s main thread. The callback function must not block the thread. And should be lightweight. Otherwise, the main thread will be blocked, and the whole Colonio process will be slow or freeze. This option is for developing wrappers for JS, Golang, and others. You should not use this option if you don’t know the internal structure of Colonio.

default: false

unsigned int max_user_threads #

max_user_threads describes the maximum number of user threads.

Callback functions of Colonio will be run on user threads when disable_callback_thread is false. User threads are created as needed up to this variable. The developer should set this value to create enough threads when callback functions depend on the other callback functions’ return.

default: 1

std::function< void(Colonio &colonio, const std::string &json)> logger_func #

logger is for customizing the the log receiver.

logger method call when output log. You should implement this method to customize log. Colonio outputs 4 types log, info, warn, error, and debug. Default logger output info level log to stdout, others are output to stderr. You can customize it by using this interface. Note that the method could be call by multi threads. You have to implement thread-safe if necessary. Log messages past from colonio are JSON format having keys below.

file : Log output file name. level : The urgency of the log. line : Log output line number. message : Readable log messages. param : The parameters that attached for the log. time : Log output time.

Parameters #

• json JSON formatted log message.

ColonioConfig() #

class colonio::Error #

class colonio::Error
  : public exception

Error information. This is used when the asynchronous method calls a failed callback and is thrown when an error occurs in a synchronous method.

See also: ErrorCode

const bool fatal #

True if the error is fatal and the process of colonio can not continue.

const ErrorCode code #

Code to indicate the cause of the error.

const std::string message #

A detailed message string for display or bug report.

const unsigned long line #

The line number where the exception was thrown (for debug).

const std::string file #

The file name where the exception was thrown (for debug).

Error(bool fatal,ErrorCode code,const std::string & message,int line,const std::string & file) #

Construct a new Error object.

Parameters #

• fatal True if the error is fatal and the process of colonio can not continue.
• code Code to indicate the cause of the error.
• message A detailed message string for display or bug report.
• line The line number where the exception was thrown.
• file The file name where the exception was thrown.

const char * what() const #

Override the standard method to output message.

Returns #

const char* The message is returned as it is.

class colonio::MessagingResponseWriter #

virtual ~MessagingResponseWriter() #

void write(const Value &) #

class colonio::Value #

Values in colonio are represented as instance of colonio::Value class.

Value() #

Value(const Value & src) #

Copy construct a new Value object.

Parameters #

• src The copy source object.

Value(bool v) #

Construct a new boolean Value object.

Parameters #

• v The source value of the object.

Value(int64_t v) #

Construct a new integer Value object.

Parameters #

• v The source value of the object.

Value(double v) #

Construct a new float number Value object.

Parameters #

• v The source value of the object.

Value(const char * v) #

Construct a new string Value object.

The char array is converted using the std::string constructor, so up to the first \0 is used to create a Value object.

Parameters #

• v The source value of the object.

Value(const std::string & v) #

Construct a new string Value object.

The data was transferred to other nodes is also processed as is.

Parameters #

• v The source value of the object.

Value(const void * ptr,std::size_t siz) #

Construct a new Value object as a binary type.

Parameters #

• ptr
• len Size of binary data.

virtual ~Value() #

Destroy the Value object.

Value & operator=(const Value & src) #

Copy operation.

Parameters #

• src The copy source object.

Returns #

Value&

bool operator<(const Value & b) const #

Implementation of comparison operations for std::map and other algorithms.

This comparison operation should not be used as a semantic order in a user program.

Parameters #

• b The object to be compared.

Returns #

true

Returns #

false

template<> const T & get() const #

Extract the actual value from the object.

The value is passed as a reference type, which will be changed by the call to reset and set method. The value may be changed by the implementation of the module, such as a setter of another node. Also, depending on the implementation of the module, the value may be changed by another node’s setter, etc. Do not hold the returned values as reference types or pointers.

Parameters #

• T Native type, which corresponds to the value stored by Value object.

Returns #

const T& The value stored by Value object.

const void * get_binary() const #

size_t get_binary_size() const #

Type get_type() const #

Get the type stored by Value object.

Returns #

Type The type stored by Value object.

void reset() #

Reset the value stored by Value to null.

void set(bool v) #

Set a new boolean value for Value object.

Parameters #

• v The source value of the object.

void set(int64_t v) #

Set a new integer value for Value object.

Parameters #

• v The source value of the object.

void set(double v) #

Set a new float number value for Value object.

Parameters #

• v The source value of the object.

void set(const std::string & v) #

Set a new string for Value object.

Parameters #

• v The source value of the object.

void set(const void * ptr,std::size_t siz) #

Set a new binary data for Value object.

Parameters #

• ptr
• len

enum Type #

It represents the type that the Value has.

struct colonio::MessagingRequest #

std::string source_nid #

Value message #

uint32_t options #

struct colonio::SpreadRequest #

std::string source_nid #

Value message #

uint32_t options #

namespace colonio::LogLevel #

The levels determine the importance of the message.

const std::string ERROR(“error”) #

const std::string WARN(“warn”) #

const std::string INFO(“info”) #

const std::string DEBUG(“debug”) #

Generated by Moxygen