Authors
- Richard Frith-Macdonald (
rfm@gnu.org
)
-
Copyright: (C) 2012 Free Software Foundation, Inc.
- 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
- (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.
- (NSArray*)
alarms;
Returns an array containing all the currently
active alarms.
- (NSArray*)
backups;
Returns an array of backup destinations (if set).
See
-setBackups:
for more information.
- (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.
- (id)
init;
Description forthcoming.
- (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.
- (BOOL)
isRunning;
Returns a flag indicating whether the receiver is
actually operating.
- (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.
- (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.
- (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).
- (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.
- (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.
- (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
@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.
@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.
@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.
@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.
@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.
@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.
@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.
@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.
@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.
@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.
@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.
@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.
@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.
@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.
- 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
- (void)
alarmFwd: (
EcAlarm*)event;
Forward an alarm event.
- (void)
domanageFwd: (NSString*)managedObject;
Forward a domanage event.
- (void)
unmanageFwd: (NSString*)managedObject;
Forward an unmanage event.
- 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
- (oneway void)
alarm: (in bycopy
EcAlarm*)event;
Passes an alarm to the destination.
- (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.
- (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.