tsload 0.2.0-beta documentation

HostInfo Object

Abstract hi object container implementation

Host object may be a device, filesystem or network interface - so
generally speaking it is any entity that could be utilized by loader or monitor.

Objects are split into several subsystems:

hi_obj_subsys contains global table of implemented subsystems. Each subsystem has
global list of objects (which contains not only root objects) accessible by hi_obj_list.

Each object represented by implementation-specific structure, but each begins
with header hi_object_header_t. Also, each subsystem implements their own object
methods which proxy requests to hi_object, and custom operations:

hi_dsk_list(...) -> hi_obj_list(HI_SUBSYS_DISK, ...) -> subsys->ops->op_probe [hi_dsk_probe]

Objects are forming a hierarchy: each object may have multiple parents (but refer
only to first of them, usually object has only one parent, so this is enough) and
multiple children. Every children reference is represented by hi_object_child_t structure.
First child node is embedded into its object, if multiple parents are exist, it is
allocated from heap.

Object lifetime:

1. hi_*_create - creates new object (implemented by subsystem)
      -> hi_obj_header_init
      -> hi_obj_child_init
  (Subsystem fills in object information)
2. hi_*_add
      (Creates object name)
         -> hi_obj_add

3 (optional). hi_obj_attach

...

n. hi_obj_destroy
        -> subsys->ops->op_dtor

When list of objects is accessed for first time, we call subsys->op->op_probe
to read it from operating system. Current subsystem state is identified by subsys->state field:

              hi_obj_list            op_probe
 NOT_PROBED -------------> PROBING -----------> OK -------+
     ^                               |                    |
     |                               +--------> ERROR ----+
     |                                                    |
     +----------------------------------------------------+
                 hi_obj_destroy_all || reprobe

Functions

hi_obj_header_init


Initialize object header

ARGUMENTS

void hi_obj_header_init(hi_obj_subsys_id_t sid, hi_object_header_t* hdr, const char* name)

hi_obj_attach

public


Attach object hdr to parent

ARGUMENTS

NOTES
Do not call this function directly -- use subsystem's equivalent

LIBEXPORT void hi_obj_attach(hi_object_t* hdr, hi_object_t* parent)

hi_obj_detach

public


Detach object from parent

ARGUMENTS

NOTES
Do not call this function directly -- use subsystem's equivalent

LIBEXPORT void hi_obj_detach(hi_object_t* hdr, hi_object_t* parent)

hi_obj_destroy

public


Destroy object and its children recursively (if no more parents
for this child left). If object is not root (has parents), doesn't
destroy anything and returns 1, otherwise returns 0.

Frees child handlers then calls subsystem-specific destructor

LIBEXPORT int hi_obj_destroy(hi_object_t* object)

hi_obj_destroy_all

public


Destroy all objects for subsystem sid

ARGUMENTS

LIBEXPORT void hi_obj_destroy_all(hi_obj_subsys_id_t sid)

hi_obj_add

public


Add object to global list

NOTES
Do not call this function directly -- use subsystem's equivalent

LIBEXPORT void hi_obj_add(hi_obj_subsys_id_t sid, hi_object_t* object)

hi_obj_find

public


Find object by it's name

TODO: hashmap cache?

ARGUMENTS

NOTES
Do not call this function directly -- use subsystem's equivalent

LIBEXPORT hi_object_t* hi_obj_find(hi_obj_subsys_id_t sid, const char* name)

hi_obj_list

public


Get list head of hostinfo object list

ARGUMENTS

RETURN VALUES
list head or NULL if probe error occured, or subsystem identifier is invalid

NOTES
Do not call this function directly -- use subsystem's equivalent

LIBEXPORT list_head_t* hi_obj_list(hi_obj_subsys_id_t sid, boolean_t reprobe)

hi_obj_load_helper

public


Load HostInfo helper library

location of helper libraries is determined by hi_obj_modpath variable
and should be deduced or taken from environment by application before
hi_obj_init() is called.

Call this function in context of subsys->op_init() call.

ARGUMENTS

RETURN VALUES
non-zero value on error, or 0 if all went fine

NOTES
Purpose of the helpers is to remove number of statically linked libraries from libhostinfo.so. So if helper loading was unsuccessful this function still return 0. So check helper->loaded to ensure that helper is useable.

LIBEXPORT int hi_obj_load_helper(hi_obj_helper_t* helper, const char* libname, const char* probefunc)

hi_obj_unload_helper

public


Release resources used by HostInfo helper

Call this function in context of subsys->op_fini() call.

ARGUMENTS

LIBEXPORT void hi_obj_unload_helper(hi_obj_helper_t* helper)

hi_obj_fini, hi_obj_init

public

LIBEXPORT int hi_obj_init(void)
LIBEXPORT void hi_obj_fini(void)

tsobj_hi_format_all

public

LIBEXPORT tsobj_node_t* tsobj_hi_format_all(boolean_t reprobe)

hi_for_each_child_safe, hi_for_each_object, hi_for_each_object_safe, hi_for_each_child


Iterate over object list or its children

hi_for_each_object and hi_for_each_object_safe take list returned by
hi_obj_list() and its equivalent and return entries as hi_object_t*.

hi_for_each_child and hi_for_each_child_safe take parent object represented
as hi_object_t* and return entries of hi_object_child_t*.

NOTES
these macros are working with hi_object_t raw objects to access specific HostInfo object like CPU or disk, use subsystem conversion operations

REFERENCE
list_for_each_entry, list_for_each_entry_safe

#define hi_for_each_object(object, list)
#define hi_for_each_object_safe(object, next, list)
#define hi_for_each_child(child, parent)
#define hi_for_each_child_safe(child, next, parent)

Types

hi_obj_subsys_id_t

typedef enum {
    HI_SUBSYS_CPU,
    HI_SUBSYS_DISK,
    HI_SUBSYS_NET,
    HI_SUBSYS_FS,

    HI_SUBSYS_MAX
} hi_obj_subsys_id_t;

hi_obj_subsys_ops_t


HostInfo object subsystem operations

MEMBERS

typedef struct {
    hi_obj_probe_op        op_probe;
    hi_obj_dtor_op        op_dtor;
    hi_obj_init_op        op_init;
    hi_obj_fini_op        op_fini;

    hi_obj_tsobj_format_op     op_tsobj_format;
} hi_obj_subsys_ops_t;

hi_obj_subsys_t

typedef struct {
    hi_obj_subsys_id_t     id;
    char*                 name;
    hi_obj_subsys_ops_t* ops;
    list_head_t             list;
    int                     state;
} hi_obj_subsys_t;

hi_obj_helper_t

typedef struct {
    boolean_t loaded;
    
    AUTOSTRING char* path;
    plat_mod_library_t lib;
    
    hi_obj_probe_op    op_probe;
} hi_obj_helper_t;

hi_object_child_t

typedef struct {
    struct hi_object_header* parent;
    struct hi_object_header* object;

    list_node_t         node;
    int                type;
} hi_object_child_t;

typedef struct hi_object_header


Header of all HostInfo objects

Should be included for all corresponding structures as first member

MEMBERS

typedef struct hi_object_header {
    hi_obj_subsys_id_t            sid;
    hi_object_child_t            node;
    list_node_t                    list_node;
    list_head_t                 children;

    unsigned short                ref_count;

    AUTOSTRING char*            name;
} hi_object_header_t;



typedef hi_object_header_t  hi_object_t;