begin is
called from the mapper to start a transaction when adding, updating or
removing nodes in the node tree. The initiator argument specifies
the initiator processor, this can be nil if the transaction is not initiated
by a processor. The initiator will be passed as cpu
argument to callback functions in the
osa_node_tree_notification interface. The function returns an
ID to be used when calling end.
end is called from the mapper to end a transaction. This should be called at the end of a transaction when all modifications to the node tree are complete. The transaction_id argument should be the value returned from the begin method that started the transaction. Stacked calls to begin and end are possible, then the transaction will be ended when the first begin is ended. The begin methods must be ended in the opposite order that they were called. For stacked calls to begin only the initiator of the first call to begin will be used.
create creates a new node tree and associates mapper with it. The properties of the root node for the new tree are set through props which is a dictionary. The returned value is the node ID of the created root node.
add adds a new node rooted at parent_id. The new node gets the properties specified by props which is a dictionary. The returned value is the node ID of the newly added node.
update updates the properties of a node in the node tree. node_id specifies the node to be updated and props is a dictionary of the properties that should be updated.
set_property updates one property of a node in the node tree. This is similar to update but there is no need to build up a dictionary. node_id specifies the node to be updated, key the key of the property to be updated and value the value to update the property with.
reset resets a node, node_id, to the properties specified by props. All the children for the node will be removed and all properties except the ones in props will be removed. If the reset node was previously active it will be deactivated.
All methods have the limitation that data and dictionary types are not supported as the value of a property. The keys of the props dictionary must all be of string type.
remove removes the node with the ID specified by node_id from the node tree.
event registers a new event, associated with the given node_id. The event_name argument is the name of the event, this name can also be used by a user to only listen to a specific event type per node tree. The event_data argument is the data associated with the event and it is up to the responsible tracker to document its exact form. An event differes from other properties in the way that they are not persistent.
activate sets node_id as the active node for processor cpu in the node tree where node_id exists. All the ancestors of node_id will also be set as active. Any previously active node for cpu will be deactivated.
deactivate deactivates processor cpu in the node tree where node_id exists. The node_id argument should be set to the node that was previously active on cpu in the node tree.
register_formatter registers a callback function which will be
called when the property specified by the key argument should be
formatted in a specific way. This is typically called from
"get_formatted_properties" in the
osa_node_tree_query interface. This is useful for
systems where an integer property should be formatted in hexadecimal to make
a closer match to the target OS mapper of that property. For example, a node
with the following properties:
{"name": "foo", "tid": 4711}
could then be formatted as:
{"name": "foo", "tid": "0x1267"}
The function itself must return a string, given as an attr_value_t. The
mapper must have been registered by calling the create function
in the osa_node_tree_admin interface before registering a
formatter.
The register_formatter function returns a cancel id that can be passed to the unregister_formatter function to unregister the formatting function. Registering a new formatter on the same node_id and key as a previous formatter will override the previous formatter with the new one. This is useful when dealing with stacked trackers and a sub-tracker needs to register a formatter for a node that already have a registered formatter.
unregister_formatter unregisters a previously registered formatter function using the register_formatter function.
SIM_INTERFACE(osa_node_tree_admin) {
transaction_id_t (*begin)(conf_object_t *NOTNULL obj,
conf_object_t *initiator);
void (*end)(conf_object_t *NOTNULL obj,
transaction_id_t transaction_id);
node_id_t (*create)(conf_object_t *NOTNULL obj,
conf_object_t *NOTNULL mapper, attr_value_t props);
node_id_t (*add)(conf_object_t *NOTNULL obj,
node_id_t parent_id, attr_value_t props);
void (*update)(conf_object_t *NOTNULL obj, node_id_t node_id,
attr_value_t props);
void (*remove)(conf_object_t *NOTNULL obj, node_id_t node_id);
void (*event)(conf_object_t *NOTNULL obj, node_id_t node_id,
const char *event_name, attr_value_t event_data);
void (*activate)(conf_object_t *NOTNULL obj, node_id_t node_id,
conf_object_t *NOTNULL cpu);
void (*deactivate)(conf_object_t *NOTNULL obj, node_id_t node_id,
conf_object_t *NOTNULL cpu);
cancel_id_t (*register_formatter)(
conf_object_t *NOTNULL obj, node_id_t node_id,
const char *NOTNULL key,
bool recursive, attr_value_t (*formatter)(attr_value_t val));
void (*unregister_formatter)(
conf_object_t *NOTNULL obj, cancel_id_t node_id);
void (*reset)(conf_object_t *NOTNULL obj,
node_id_t node_id, attr_value_t props);
void (*set_property)(conf_object_t *NOTNULL obj, node_id_t node_id,
const char *key, attr_value_t value);
};
#define OSA_NODE_TREE_ADMIN_INTERFACE "osa_node_tree_admin"