1. MPI Version 2 Asaf Yaffe July 2006

2. Agenda Why redesign MPI Requirements Design Concepts –Events –Event Groups Event Filters Enabling/Disabling Events –Data Requests Sample MPI Client Code

3. Why Redesign MPI? The current design does not scale well –SData is cluttered with unrelated fields and will be even more so when new events and data is added –Extending SData to support more than 32 data types is clumsy –Event selectivity model fits only call-graph events Does not allow different selectivity function callback prototypes Usability –Implicit grouping of events (for selectivity and enable/disable) is documented but not reflected in the formal API –The DataRequest mechanism is complex Function arguments arent natural –.NET and Java specific extensions are not cleanly separated This issue has been addressed separately and is not part of this design

4. Requirements Support multiple selectivity models for events Event handlers should work with event- specific data –Should include only relevant data items Selectivity and Enable/Disable operations should be applied to groups of related events and not to a specific event –e.g. Call Graph events, Heap events

5. MPI v2 API Design Concepts

6. Events (1/2) Martini provides information to profilers through a publish- subscribe event model Clients handle events by implementing Event Observers and registering them with the Martini runtime –A specific MPI Event Observer interface is defined for each event All Event Observer interfaces derive from a generic IEventObserver interface –The interface defines a minimal set of shared operations EventDataTypes() –specifies the data items to send with the event –The generic interface does not define a HandleEvent callback Each Event Observer interface defines an event-specific HandleEvent callback function HandleEvent callbacks differ in their event data type argument These callbacks are used by MPI to dispatch the event to the client

7. Events (2/2) An observer interface for the New Method event Each event handler is represented by a specific interface. To respond to an event, the client implements and registers the Observer which represents the event it is interested in An observer interface for the Object Free event best seen in slide show mode

8. Event Groups (1/2) Event Groups enables some operations to be applied on a group of events rather than on individual events –Groups are not new to MPI. In the previous version they were implicitly defined and documented, but the concept was not reflected in the API definition –Examples Event selectivity defined for the Method Enter event is automatically applied to the New Method and Method Leave events Enabling (disabling) the Method Enter event automatically enables (disables) the New Method and Method Leave events In MPI v2, related events are explicitly grouped together –These groups are hard-coded in the API. –Each group is identified by a unique name (defined by an EEventGroup enumerator). –Enabling/disabling events and setting event filter operations are defined for event groups, rather than for individual events

9. Event Groups (2/2) Supported Event Groups –EG_CALL_GRAPH: New Method, Method Enter and Method Leave –EG_HEAP: Object Alloc, Object Free –EG_MONITOR: Monitor events (TBD) More groups can be added if necessary The following operations are supported for Event Groups only (not for individual events) –Enabling or disabling events –Defining event selectivity

10. Event Filters (1/2) Filters define the selectivity criterion for events –Associated with Event Groups –Applied to all events in the group –Decoupled from Event Observers The event selectivity is not tied to a specific event Clients define filters by implementing Event Filter interfaces, and registering them with MPI using a specific API (SetEventGroupFilter) –Each Event Group has a corresponding Filter interface which defines a ShouldNotify() operation. The signature of this operation is specific to each group. –ShouldNotify() is the callback used by MPI to query the client for selectivity criterion (for example, during BCI for generating Method Enter/Leave events)

11. Event Filters (2/2)

12. Enabling and Disabling Events Enabling and Disabling Events is supported for Event Groups –Cant enable/disable a specific event Clients enable or disable events by using the following APIs –EnableEventGroup(EEventGroup group) –DisableEventGroup(EEventGroup group)

13. Data Requests No one-size-fits-all Data Request operation A Data Request operation is defined for each data domain (module, class, method, thread, object) –GetModuleInfo(), GetClassInfo(), GetMethodInfo(), etc… –Each domain defines its own structures (SModuleInfo, SClassInfo, etc…) –Structures are not shared between different domains –Structures may be shared with relevant event data Improved usability –The query key (method id, module id, etc) is specified as an API parameter –Resolves the duality of the SData structure used in MPI v1.

14. The MPI v2 API (1/2) RegisterEvent API –Applicability: profiler initialization only –Paramters: [in] Client ID [in] Event Observer object SetEventGroupFilter API –Applicability: profiler initialization only –Parameters: [in] Client ID [in] Event Group (one of EEventGroup values) [in] Event Filter object Enable/DisableEventGroup –Applicability: profiler initialization and/or MPI live phase –Parameters: [in] Client ID [in] Event Group (one of EEventGroup values)

15. The MPI v2 API (2/2) GetModule/Class/Method/Thread/ObjectInfo APIs –Applicability: MPI live phase only –Parameters: [in] Client ID [in] Query key (module/class/method/thread/object id) [in] Requested Data Items (Bit Set) [out] module/class/method/thread/object data All other APIs are same as in MPI v1.

16. Sample MPI Client Code // Define New Method event observer class CNewMethodEvent: public INewMethodEventObserver { BitSet EventDataTypes() { return DR_METHOD_ID | DR_METHOD_NAME | DR_METHOD_SIGNATURE; } void HandleEvent(SNewMethodData &data) { printf("New Method Event received: %d, %s(%s)\n", data.id, data.name, data.signature); } }; // Define Object Allocated event observer class CObjectAllocEvent: public IObjectAllocEventObserver { BitSet EventDataTypes() { return DR_THREAD_ID | DR_OBJECT_ID | DR_OBJECT_INFO; } void HandleEvent(SHeapData &data) { cout << "Object Alloc Event received" << endl; } };

17. Sample MPI Client Code Defining Event Filters // Define Heap Events selectivity: // track allocations for class mystuff.Foo only class CHeapFilter : public IHeapFilter { bool ShouldNotify(SHeapFilter &filter) { if (strcmp(filter.szClassName, "mystuff.Foo") == 0) { return true; } return false; } };

18. Sample MPI Client Code Registering Events CNewMethodEvent newMethodEvent; CObjectAllocEvent objectAllocEvent; TResult res; // Register to non-selective EV_NEW_METHOD (initially enabled) res = mpi->RegisterEvent(myClientId, newMethodEvent); // Register to selective EV_OBJECT_ALLOC (initially enabled) res = mpi->RegisterEvent(myClientId, objectAllocEvent); CHeapFilter heapFilter; mpi->SetEventGroupFilter(myClientId, EG_HEAP, heapFilter);