Developer Documentation
PATH  WebObjects 4.5 Documentation > EOControl Reference

Table of Contents

EOEventCenter


Inherits from:
NSObject
Declared in:
EOControl/EOEventCenter.h




Class Description


EOEventCenter collects and manages EOEvents to allow you to measure the duration of operations in your applications. Measurements allow you to profile an application and optimize its execution time. For this, Enterprise Objects Framework and WebObjects instrument key portions of their code to measure the elapsed time of functions and methods.

For more information on the event logging feature and on instrumenting your own code for event logging, see the following sections:




Method Types


Registering event classes for logging
+ registerEventClass:classPointer:
+ registerEventClass:handler:
+ registeredEventClasses
+ setRecordsEvents:forClass:
+ recordsEventsForClass:
Logging events
+ newEventOfClass:eventType:
+ markAtomicEvent:info:
+ markStartOfEvent:info:
+ markEndOfEvent:
+ cancelEvent:
Accessing event centers
+ currentCenter
+ allCenters
Accessing events
+ allEvents
- allEvents
+ eventsOfClass:eventType:
- eventsOfClass:eventType:
+ rootEvents
- rootEvents
+ rootEventsByDuration
Resetting and suspending event logging
+ resetLogging
- resetLogging
+ suspendLogging
+ resumeLogging


Class Methods



allCenters

+ (NSArray *)allCenters

Returns all event centers. Typically used only for post-processing of events and statistics gathering. Note that there is one event center per thread.

cancelEvent:

+ (void)cancelEvent:(EOEvent *)event

Cancels the recording of an in-progress event. This method doesn't work with atomic events or with events that have already been ended with markEndOfEvent:.
Note: Don't invoke this method directly. Instead, use the corresponding function, which is much more efficient:
EOCONTROL_EXTERN void EOCancelEvent(EOEvent *event)


Generally you cancel an event when the operation being logged is aborted. For example, the ODBCAdaptorChannel cancels an "Open Channel" event if the openChannel method doesn't successfully open a connection to the database:

- (void)openChannel
{
    Class loggingODBCAdaptor; // Assume this exists;
    ODBCAdaptorEvent *e = nil;
    // Irrelevant code omitted.
    // Check if we are logging, and if so, start a new event
    if (loggingODBCAdaptor) {
        e = EONewEventOfClass (loggingODBCAdaptor, @"openChannel");
        EOMarkStartOfEvent (e, nil);
    }

    // Get the connection.

    if (/* Couldn't secure a connection to the database */) {
        EOCancelEvent (e);
        // Raise an exception
    }

    // Perform additional housekeeping

    // Mark the end of the event.
    if (e)
        EOMarkEndOfEvent (e);
}



currentCenter

+ (EOEventCenter *)currentCenter

Returns the event center for the calling thread.

allEvents

+ (NSArray *)allEvents

Returns an array of all the events logged in all the event centers. The events in the returned array are in no particular order.

See Also: - allEvents



eventsOfClass:eventType:

+ (NSArray *)eventsOfClass:(Class)aClass eventType:(NSString *)type

Returns an array of all events (from all the event centers) that are instances of aClass and whose type is type. Specifying Nil for the class returns events of any class. Similarly, specifying nil for the type returns events of any type.

See Also: - eventsOfClass:eventType:



resetLogging

+ (void)resetLogging

Discards all events in all event centers, restarting event collection for the entire application.

See Also: - resetLogging



rootEvents

+ (NSArray *)rootEvents

Returns all events from all event centers that are recorded at the root level; that is, it returns the events that don't have parent events.

See Also: - rootEvents



markAtomicEvent:info:

+ (void)markAtomicEvent:(EOEvent *)event info:(id)info

Initializes event, a newly allocated event, as an atomic event, and assigns it's info to info. The newly allocated event is usually created with the EOEventCenter method newEventOfClass:eventType:.
Note: Don't invoke this method directly. Instead, use the corresponding function, which is much more efficient:
EOCONTROL_EXTERN void EOMarkAtomicEvent(EOEvent *event, id info)




markEndOfEvent:

+ (void)markEndOfEvent:(EOEvent *)event

Marks the time event ended.
Note: Don't invoke this method directly. Instead, use the corresponding function, which is much more efficient:
EOCONTROL_EXTERN void EOMarkEndOfEvent(EOEvent *event)




markStartOfEvent:info:

+ (void)markStartOfEvent:(EOEvent *)event info:(id)info

Marks event, a newly allocated event, to be a branch event (that possibly has nested subevents), and assigns it's info to info. The newly allocated event is usually created with newEventOfClass:eventType:.

There is a limit on the number of events the event logging system logs-200,000 by default. You can change the limit using the user default EOEventLoggingLimit. When the logging limit is reached, the logging system attempts to purge old events before logging new ones. If the system is unable to purge old events, event logging is aborted.

The system's attempt to purge events can fail if the event logging limit is too small. This happens because the event system can't purge the first event logged, and it can't purge unclosed branch events.


Note: Don't invoke this method directly. Instead, use the corresponding function, which is much more efficient:
EOCONTROL_EXTERN void EOMarkStartOfEvent(EOEvent *event, id info)




newEventOfClass:eventType:

+ (id)newEventOfClass:(Class)aClass eventType:(NSString *)aType

Creates an event of the desired class and type. To maximize performance, alloc is not invoked to allocate the new event; however, all instance variables are initialized to zero.
Note: Don't invoke this method directly. Instead, use the corresponding function, which is much more efficient:
EOCONTROL_EXTERN id EONewEventOfClass(Class aClass, NSString *type)




recordsEventsForClass:

+ (BOOL)recordsEventsForClass:(Class)eventClass

Returns YES if the application logs events of the eventClass class.

registerEventClass:classPointer:

+ (void)registerEventClass:(Class)aClass classPointer:(Class *)classP

Registers aClass as an event class. The classP argument is a flag set by the event logging system and used in instrumented code to specify whether or not event logging is enabled for classP. The event logging system sets classP to aClass when instrumented code should log events of aClass, or to Nil if events of aClass shouldn't be logged.

If the EOEventLoggingEnabled user default is set to YES, this method enables logging for aClass. Programmatically, you can selectively enable or disable logging for a specific class with setRecordsEvents:forClass:. It is more common, however, for users to enable and disable logging of a particular class through the WOEventSetup page-for more information, see "WOEventSetup page" .

Typically registerEventClass:classPointer: is invoked in the initialize method of the class whose code you're instrumenting for event logging. For example, the following is the relevant portion of ODBCAdaptor's initialize method from ODBCAdaptor.m:

+ (void)initialize
{
    // Irrelevant initialization code omitted.
    if ([self class] == [ODBCAdaptor class]) {
        // register for logging
        [EOEventCenter registerEventClass:[ODBCAdaptorEvent class]
                classPointer:&loggingODBCAdaptor];
    }
}

Where loggingODBCAdaptor is declared in ODBCAdaptorEvent.h as follows:

    extern Class loggingODBCAdaptor;

And initially defined in ODBCAdaptor.m as

    Class loggingODBCAdaptor = Nil;

When the event logging system enables logging for the ODBCAdaptorEvent class, it sets loggingODBCAdaptor to the ODBCAdaptorEvent class. Code that is instrumented for logging checks this variable to determine whether or not to create events, for example:

ODBCAdaptorEvent *event = nil;
// Check if we are logging, and if so, start a new event
if (loggingODBCAdaptor) {
    event = EONewEventOfClass (loggingODBCAdaptor, @"openChannel");
    EOMarkStartOfEvent (event, nil);
}



registerEventClass:handler:

+ (void)registerEventClass:(Class)aClass handler:(id <EOEventRecordingHandler>)handler

Registers aClass as an event class. The handler argument is an object that the event logging system notifies when event logging is enabled or disabled for aClass.

If the EOEventLoggingEnabled user default is set to YES, this method enables logging for aClass. Programmatically, you can selectively enable or disable logging for a specific class with setRecordsEvents:forClass:. It is more common, however, for users to enable and disable logging of a particular class through the WOEventSetup page-for more information, see "WOEventSetup page" .

Typically registerEventClass:handler: is invoked in the initialize method of the class whose code you're instrumenting for event logging. For example, the following code could be used in the ODBCAdaptor's initialize method in ODBCAdaptor.m:

+ (void)initialize
{
    // Irrelevant initialization code omitted.
    if ([self class] == [ODBCAdaptor class]) {
        // register for logging
        [EOEventCenter registerEventClass:[ODBCAdaptorEvent class]
                handler:handler];
    }
}

When the event logging system enables logging for the ODBCAdaptorEvent class, it sends handler a setLoggingEnabled message with YES as the flag and ODBCAdaptorEvent as the event class. handler is responsible for enabling logging in the instrumented code. For example, handler could set a flag that instrumented code such as the following checks:

BOOL loggingODBCAdaptor; // Assume this exists.
ODBCAdaptorEvent *event = nil;
// Check if we are logging, and if so, start a new event
if (loggingODBCAdaptor) {
    event = EONewEventOfClass (ODBCAdaptorEvent, @"openChannel");
    EOMarkStartOfEvent (event, nil);
}

In this example, handler is responsible for updating the loggingODBCAdaptor variable.



registeredEventClasses

+ (NSArray *)registeredEventClasses

Returns all the event classes registered in the application.

resumeLogging

+ (void)resumeLogging

Resumes event logging in all centers. However, logging doesn't actually resume until each invocation of suspendLogging is paired with an invocation of resumeLogging. Invoking resumeLogging without a corresponding suspendLogging isn't harmful.

rootEventsByDuration

+ (NSArray *)rootEventsByDuration

Returns all root events from all event centers, sorted by decreasing duration.

See Also: + rootEvents, - rootEvents



setRecordsEvents:forClass:

+ (void)setRecordsEvents:(BOOL)flag forClass:(Class)eventClass

Sets according to flag whether event centers record events of the eventClass class (and its subclasses). By default, event centers don't record events of any class. You can selectively enable logging for a particular event class with this method. To enable event logging for all event classes, set the user default EOEventLoggingEnabled. Then, you can selectively disable logging for a particular event with this method.

suspendLogging

+ (void)suspendLogging

Suspends event logging in all event centers. Each invocation of suspendLogging must be paired with an invocation of resumeLogging to resume event logging.


Instance Methods



allEvents

- (NSArray *)allEvents

Returns the receiver's events (in no particular order).

eventsOfClass:eventType:

- (NSArray *)eventsOfClass:(Class)aClass eventType:(NSString *)type

Returns the subset of the receiver's events that are instances of aClass and that have the type type. Specifying Nil for the class returns events of any class. Similarly, specifying nil for the type returns events of any type.

resetLogging

- (void)resetLogging

Discards all events in the event center for the calling thread.

See Also: + resetLogging



rootEvents

- (NSArray *)rootEvents

Returns the receiver's events that were recorded at root level; that is, returns the events that don't have a parent event.

See Also: + rootEvents, + rootEventsByDuration




Table of Contents