instrumentation_order

Description

This interface is used to control the dispatch order of connected instrumentation. It is implemented by instrumentation providers that have the ability to change the order in which instrumentation events occur. This works by associating every instrumentation event with a connection object. It is up to the provider to supply a way to do this. See the cpu_instrumentation_subscribe interface for an example. Most users of any instrumentation will only be observing the state of the provider, in which case the order is unimportant. However, if users of instrumentation may change the behavior of the provider, this interface may be useful.

The default order for callbacks that should be honored by all providers, where possible, regardless if they implement the instrumentation_order interface or not is:

1. all anonymous connections, i.e. NULL connections, in registration order
2. connection order, which if not re-ordered will be the connection registration order
3. callback registration order

The get_connections method should return an attr_value_t list with connection objects that represent the current order. The first element in the list is the first object in the dispatch order, etc.

The move_before method moves the connection given by the connection argument before the connection given by the anchor argument. If the anchor is NULL the connection will be moved last. The given connection objects must be present in the current dispatch order for this to succeed.

SIM_INTERFACE(instrumentation_order) {
        // Returns an object list in the connection order
        attr_value_t (*get_connections)(conf_object_t *obj);
        
        bool (*move_before)(conf_object_t *self, conf_object_t *connection,
                            conf_object_t *before); 
};
#define INSTRUMENTATION_ORDER_INTERFACE "instrumentation_order"

Execution Context

Global Context for all methods, but must be called from a callback receiving a handle of type instruction_handle_t.