Description

Base class for Grabba listener classes; not intended for external use.

Child classes such as GrabbaConnectionListener add the relevant events to this base, with each one providing a different set of events. This class should not be instantiated directly from outside the Grabba driver; use the appropriate subclass(es) instead.

Each event may invoke callbacks in two ways:

Subclassing - the relevant event methods are called directly
- This approach is recommended wherever feasible, due to its simplicity and low latency.
- To use it, create an object of a suitable subclass, which overrides the desired event method(s).
Delegation - event methods trigger method calls for a delegate object
- This approach is only recommended when the callback class must inherit from a different base class
- To use it, create an object of the desired class, create an object of a class which implements the appropriate protocol, then set the delegate property of the former to point to the latter.

Note: Delegation will be disabled for an event if that event's method is subclassed, unless the subclass calls the superclass' equivalent method from within its override thereof.

By default, each listener object will register itself for callbacks upon construction, and deregister itself at destruction; the enable and disable methods may be used if an object requires manual control over when its callbacks are triggered.

Template Parameters

ProtocolType Type of the delegate protocol which will be used here, e.g. id<GrabbaConnectionProtocol> for the GrabbaConnectionListener child class

Thread safety: This interface is intended to be thread-safe; any classes deriving or delegating from it should ensure that the relevant methods are callable from any thread.

Inheritance diagram for GrabbaListener< ProtocolType >:

Instance Methods
(void)	- disable
	Disable listening for events from this object, if not already disabled. More...

(void)	- enable
	Enable listening for events from this object, if not already enabled. More...

(instancetype _Nullable)	- init
	Default initialiser - builds an object then enables event callbacks to it. More...

(instancetype _Nullable)	- initWithEnabled:
	Initialiser which allows control over whether event callbacks should be enabled. More...

Properties
ProtocolType _Nullable	delegate
	Delegate for receiving events from non-subclassed listener objects; defaults to nil. More...

Method Documentation

◆ disable()

- (void) disable

Disable listening for events from this object, if not already disabled.

This will remove the listener object from the relevant event handler, if it had previously been added. Callbacks will no longer be triggered on this object, although they may be re-enabled by calling enable.

Note: This method should not be overridden.

◆ enable()

- (void) enable

Enable listening for events from this object, if not already enabled.

This will add the listener object to the relevant event handler, if it has not already been added. Events will then trigger callbacks on this object until it is destroyed or disable is called.

Note: This method should not be overridden.

◆ init()

- (instancetype _Nullable) init

Default initialiser - builds an object then enables event callbacks to it.

Returns: Pointer to initialised object if initialisation succeeded; nil if it failed

◆ initWithEnabled:()

- (instancetype _Nullable) initWithEnabled: (BOOL) startEnabled

Initialiser which allows control over whether event callbacks should be enabled.

Parameters

startEnabled If YES, the newly-allocated listener object is added to the relevant event handler, enabling receipt of event callbacks. If NO, no callbacks are received until enable is called.

Returns: Pointer to initialised object if initialisation succeeded; nil if it failed

Property Documentation

◆ delegate

- (ProtocolType _Nullable) delegate

readwritenonatomicweak

Delegate for receiving events from non-subclassed listener objects; defaults to nil.

Delegation may be used as an alternative to subclassing for receiving event callbacks. Any Grabba-defined listener class object (as opposed to a subclass thereof) will pass events on to a delegate, if one has been set and it has implemented the relevant protocol method.

If the delegate is to be written to whilst a callback to it is in progress, the write operation will block until that operation has completed. This ensures thread-safety.

Note: Delegates must provide thread-safe implementations of all protocol methods; no guarantees are made about which thread(s) they will be called from.