EcAlarmDestination class documentation

Authors

Richard Frith-Macdonald (rfm@gnu.org)

Copyright: (C) 2012 Free Software Foundation, Inc.


Contents -

  1. Software documentation for the EcAlarmDestination class
  2. Software documentation for the EcAlarmDestination(Forwarding) category
  3. Software documentation for the EcAlarmDestination protocol

Software documentation for the EcAlarmDestination class

EcAlarmDestination : NSObject

Declared in:
EcAlarmDestination.h
Conforms to:
EcAlarmDestination

The EcAlarmDestination class provides an object to act as an alarm destination which is capable of buffering, coalescing, and forwarding alarms to another destination (usually in a separate process).

The buffering and coalescing mechanism is important to prevent floods of alarms being sent over network connections.

An EcAlarmDestination instance can also be set to forward alarm information to a number of other instances as backups for the main destination.


Instance Variables

Method summary

alarm: 

- (oneway void) alarm: (in bycopy EcAlarm*)event;
Passes an alarm to the destination by adding it to a queue of alarm events which will be processed in the receivers running thread.

alarms 

- (NSArray*) alarms;
Returns an array containing all the currently active alarms.

backups 

- (NSArray*) backups;
Returns an array of backup destinations (if set).
See -setBackups: for more information.

domanage: 

- (oneway void) domanage: (in bycopy NSString*)managedObject;
Inform the destination of the existence of a managed object.
This is an indicator of a 'cold start' of that object... meaning that the object has just started up afresh, and all outstanding alarms for the object are to be cleared.
The managedObject information is added to a queue which is processed by the receiver's running thread in order to pass the information on to the destination.
If managedObject is nil, the default managed object for the current process is used.
Processes using the EcProcess class call this method automatically when they have registered with the Command server, so you don't usually need to call it explicity for the default managed object.

init 

- (id) init;
Description forthcoming.

initWithHost: name: 

- (id) initWithHost: (NSString*)host name: (NSString*)name;
Sets the name/host of the object in a remote process to which alarms should be forwarded. If this information is set then the forwarder will attempt to maintain a Distributed Objects connection to the remote object.
The host may be nil for a local connection (current machine and account), or an empty string for a network connection to the local machine, or a host name for a network connection to another machine, or an asterisk for a network connection to any available machine.

isRunning 

- (BOOL) isRunning;
Returns a flag indicating whether the receiver is actually operating.

run 

- (void) run;
This method is called from -init in a secondary thread to start handling of alarms by the receiver. Do not call it yourself.

setBackups: 

- (void) setBackups: (NSArray*)backups;
Sets an array containing EcAlarmDestination objects as backups to receive copies of the alarm and domanage/unmanage information sent to this destination.
You may set nil or an empty array to turn off backups, and may use the -backups method to get the currently set values.
Do not set up loops causing a destination to be its own backup either directly or indirectly, as this will cause alarms to be forwarded endlessly.

setCoalesce: 

- (BOOL) setCoalesce: (BOOL)coalesce;
Sets coalescing behavior for the queue of alarms and managed object changes. The default behavior is for coalescing to be turned on (so new values replace those in the queue), but setting this to NO will cause all events to be passed on (apart from repeated alarms at the same perceivedSeverity level, which are never passed one).

setDestination: 

- (id<EcAlarmDestination>) setDestination: (id<EcAlarmDestination>)destination;
Sets the destination to which alarms should be forwarded.
If nil this turns off forwarding until it is re-set to a non-nil destination.
The destination object is retained by the receiver.
Returns the previously set destination.

shutdown 

- (void) shutdown;
Requests that the receiver's running thread should shut down. This method waits for a short while for the thread to shut down, but the process of shutting down is not guaranteed to have completed by the time the method returns.

unmanage: 

- (oneway void) unmanage: (in bycopy NSString*)managedObject;
Inform the destination of the removal of a managed object.
This is an indicator of a graceful shutdown of that object... meaning that the object has been stopped intentionally and all outstanding alarms for the object are to be cleared.
The managedObject information is added to a queue which is processed by the receiver's running thread in order to pass the information on to the destination.
If managedObject is nil, the default managed object for the current process is used.
Processes using the EcProcess class call this method automatically when they are shut down normally (with a quit status of zero), so you don't usually need to call it explicity for the default managed object.



Instance Variables for EcAlarmDestination Class

_alarmLock

@protected NSRecursiveLock* _alarmLock;
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

_alarmQueue

@protected NSMutableArray* _alarmQueue;
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

_alarmsActive

@protected NSMutableSet* _alarmsActive;
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

_alarmsCleared

@protected NSMutableSet* _alarmsCleared;
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

_backups

@protected NSArray* _backups;
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

_coalesceOff

@protected BOOL _coalesceOff;
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

_destination

@protected id _destination;
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

_host

@protected NSString* _host;
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

_inTimeout

@protected BOOL _inTimeout;
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

_isRunning

@protected BOOL _isRunning;
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

_managedObjects

@protected NSMutableSet* _managedObjects;
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

_name

@protected NSString* _name;
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

_shouldStop

@protected BOOL _shouldStop;
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

_timer

@protected NSTimer* _timer;
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.




Software documentation for the EcAlarmDestination(Forwarding) category

EcAlarmDestination(Forwarding)

Declared in:
EcAlarmDestination.h
Methods called internally to forward events to the remote target of the receiver. These are provided for subclasses to override.
Method summary

alarmFwd: 

- (void) alarmFwd: (EcAlarm*)event;
Forward an alarm event.

domanageFwd: 

- (void) domanageFwd: (NSString*)managedObject;
Forward a domanage event.

unmanageFwd: 

- (void) unmanageFwd: (NSString*)managedObject;
Forward an unmanage event.

Software documentation for the EcAlarmDestination protocol

EcAlarmDestination

Declared in:
EcAlarmDestination.h
The EcAlarmDestination protocol describes the interface which must be provided by an object which handles alarms.

The sender expects to be able to 'fire and forget', sending the messages in this protocol without having to wait for a response or deal with any error conditions, so the destination must not block for a long time or raise an exception.

Method summary

alarm: 

- (oneway void) alarm: (in bycopy EcAlarm*)event;
Passes an alarm to the destination.

domanage: 

- (oneway void) domanage: (in bycopy NSString*)managedObject;
Inform the destination of the existence of a managed object.
This is an indicator of a 'cold start' of that object... meaning that the object has just started up afresh, and all outstanding alarms for the object are to be cleared.

unmanage: 

- (oneway void) unmanage: (in bycopy NSString*)managedObject;
Inform the destination of the removal of a managed object.
This is an indicator of a graceful shutdown of that object... meaning that the object has been stopped intentionally and all outstanding alarms for the object are to be cleared.