In designing an API that provides an event listening interface, it seems there are two conflicting ways of treating calls to add/remove listeners:
-
Multiple calls to addListener will only add a single listener (like adding it to a set); can be removed with a single call to removeListener.
-
Multiple calls to addListener will add a listener each time (like adding it to a list); must be balanced by multiple calls to removeListener.
I’ve found an example of each: (1) – The DOM addEventListener call in browsers only adds listeners once, silently ignoring requests to add the same listener a second time and (2) – jQuery .on behaviour adds listeners multiple times.
Most other listener APIs seem to use (2), such as SWT and Swing event listeners. If (1) is chosen, there’s also the question of whether it should fail silently or with an error when there is a request to add the same listener twice.
In my implementations, I tend to stick with (2) since it provides a cleaner setup/teardown type interface and reveals bugs where ‘setup’ is unintentionally being done twice, and is consistent with most implementations I’ve seen.
This leads me to my question – Is there a particular architecture or other underlying design that lends itself better to the other implementation? (ie: why does the other pattern exist?)
5
If you’ve got some events which you’re running into problems with managing the add/removes, I would start adding IDs.
Add a listener returns an ID, the class that added it keeps track of the ID’s for the listeners it’s added and when it needs to remove them, it calls remove listener with that/those unique ID(s).
This puts the consumers in control so that they can get compliance with Principle of Least Astonishment in the behaviour.
This means adding the same one twice adds it twice, gives a different ID for each one, and removal by ID removes only the one associated with that ID. Anyone consuming the API would expect this behaviour when they saw the sigs.
A further addition in violation of YAGNI would be a GetIds where you hand it a listener and it returns a list of IDs associated with that listener if it is capable of getting appropriate equality checks, though that is dependent on your language: is it reference equality, type equality, value equality, etc? you have to be careful here because you may return IDs which that consumer should not be removing or meddling with, therefore this exposure get’s dangerous and is ill-advised and should be unnecessary, but GetIDs is a possible addenda if you’re feeling lucky.
2
First, I would choose an approach where the order in which the listeners are added is exactly the order they will be called when the related events are triggered. If you decide to go with (1), that will mean you use an ordered set, not just a set.
Second, you should clarify a general design goal: shall your API more follow a “crash early” strategy, or an “error forgiving” strategy? This depends on the usage environment and the usage scenarios of your API. Generally, (developing mainly desktop apps) I prefer “crash early”, but sometimes it is better to tolerate some kind of errors to make the usage of an API more smooth. The requirements, for example, in embbeded apps or server apps may be different. Perhaps you discuss this with one of your potential API users?
For a “crash early” strategy, use (2), but forbid adding the same listener twice, throw an exeption if a listener is added again. Also throw an exception if one tries to remove a listener not in the list.
If you think an “error forgiving” strategy is more appropriate in your case, you could either
-
ignore the double adding of the same listener to the list – which is option (1) -, or
-
append it to the list like in (2), so it will be called twice when the events are fired
-
or you append it, but don’t call the same listener twice in case of event-triggering
Note that the listener removal should correspond to that – if you ignore double adding, you should also ignore double removal. If you allow the same listener to be added twice, it should be clear which of the two listener entries is going to be removed when one calls removeListener(foo). The last of the three bullets is most probably the least error-prone approach among those suggestions, so in case of an “error forgiving” strategy, I would go with that.
3