- Inherits from:
- NSObject
Declared in:
- EOControl/EOEventCenter.h
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:
- 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
+ (NSArray *)allCenters
+ (void)cancelEvent:(EOEvent
*)event
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); }
+ (EOEventCenter *)currentCenter
+ (NSArray *)allEvents
See Also: - allEvents
+ (NSArray *)eventsOfClass:(Class)aClass
eventType:(NSString *)type
Nil
for
the class returns events of any class. Similarly, specifying nil for
the type returns events of any type.See Also: - eventsOfClass:eventType:
+ (void)resetLogging
See Also: - resetLogging
+ (NSArray *)rootEvents
See Also: - rootEvents
+ (void)markAtomicEvent:(EOEvent
*)event
info:(id)info
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) |
+ (void)markEndOfEvent:(EOEvent
*)event
Note: Don't
invoke this method directly. Instead, use the corresponding function,
which is much more efficient:EOCONTROL_EXTERN void EOMarkEndOfEvent(EOEvent *event) |
+ (void)markStartOfEvent:(EOEvent
*)event
info:(id)info
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) |
+ (id)newEventOfClass:(Class)aClass
eventType:(NSString *)aType
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) |
+ (BOOL)recordsEventsForClass:(Class)eventClass
+ (void)registerEventClass:(Class)aClass
classPointer:(Class *)classP
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); }
+ (void)registerEventClass:(Class)aClass
handler:(id <EOEventRecordingHandler>)handler
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.
+ (NSArray *)registeredEventClasses
+ (void)resumeLogging
+ (NSArray *)rootEventsByDuration
See Also: + rootEvents, - rootEvents
+ (void)setRecordsEvents:(BOOL)flag
forClass:(Class)eventClass
+ (void)suspendLogging
- (NSArray *)allEvents
- (NSArray *)eventsOfClass:(Class)aClass
eventType:(NSString *)type
Nil
for
the class returns events of any class. Similarly, specifying nil for
the type returns events of any type.- (void)resetLogging
See Also: + resetLogging
- (NSArray *)rootEvents
See Also: + rootEvents, + rootEventsByDuration