Tolo is an event publish/subscribe framework designed to decouple different parts of your iOS application while still allowing them to communicate efficiently.
To·lo | tō - lō |
adverb
Amharic for "hurry up"
Tolo is an event publish/subscribe framework inspired by Otto and designed to decouple different parts of your iOS application while still allowing them to communicate efficiently. Traditional ways of subscribing for and triggering notifications are both cumbersome and error prone with minimal compile time error checking.
Tolo is intended for use as a singleton (though that is not required). The macros utilized in the examples below use the shared instance Tolo.sharedInstance. The use of these macros is optional, but it's highly recommended that you do use them.
Event publishing is straightforward using the macro PUBLISH(). This allows you to tell subscribers an action has occurred. An instance of any class may be published as an event and it will only be dispatched to subscribers of that type.
To publish an event, create an instance of the event you wish to publish (for example: EventProgressUpdated) and use the macro PUBLISH():
PUBLISH(event);
where event is an instance of the event type (for example: EventProgressUpdated *event = ...).
Subscription is the complement to event publishing — it lets you receive notification that an event has occurred. To subscribe to an event, use the macro SUBSCRIBE() passing in the event type you wish to subscribe to:
SUBSCRIBE(EventProgressUpdated)
{
// use the variable event — for example: self.progressView.progress = event.progress
}
In order to receive events, the class instance needs to register with Tolo. To register, simply use the macro REGISTER() and pass in a reference to the subscriber.
REGISTER(self);
When subscribing to events it is often desired to also fetch the current known value for specific events (e.g., current location, active user, etc.). To address this common paradigm, Tolo adds the concept of 'Producers' which provide an immediate callback to any subscribers upon their registration.
To create a producer, use the macro PUBLISHER():
PUBLISHER(EventProgressUpdated)
{
return instance-of-EventProgressUpdated;
}
Producers, like subscribers, must also be registered:
REGISTER(self);
When registering, the producer method will be called only once for any number of subscribers previously registered for the same event type. However, the producer method will also be called once for each new subscriber that subscribes to an event of the same type.
You may only have one producer per event type registered at a time — if multiple producers are registered, the last producer to register is used.
Since at times it may be ambiguous on which thread you are receiving callbacks, Tolo provides an enforcement mechanism to ensure you are always called on the main thread. By default, all interaction with an instance is confined to the main thread (this can be changes using the public property Tolo.forceMainThread — YES by default).
There are a few things to keep in mind. Tolo dispatches all events on the main thread. To disable that (so that events are posted on the publishing thread), set the property forceMainThread to NO: Tolo.sharedInstance.forceMainThread = NO (or replace Tolo.sharedInstance with your instance of Tolo).
You are strongly encouraged to use the macros. However, keep in mind that: 1) the macros use the default Tolo instance, b) if the subscriber/publisher prefixes are modified (these are publisherPrefix and subscriberPrfix), you can not use the SUBSCRIBE() and PUBLISHER() macros — all other macros work fine!
As I said above, the use of macros is optional. For instance, subscribing becomes: [<Tolo instance> subscribe:<subscriber instance, eg. self>] or posting simply becomes [<Tolo instance> publish:<event instance>].
Last but not least, unsubscribing. You may explicitly unsubscribe from Tolo using the UNREGISTER() macro (or [ unregister:]). However, this is optional, and thanks to the magic of ARC, Tolo will auto-unregister upon subscriber getting dealloced.
There are two easy ways of installing Tolo:
A sample application using Tolo is also included. The application is self explanatory. You can run the application and play around with it by adding as many subscribers (to a randomly generated event at 1Hz) as you like interactively. The text field also generates an event with each keystroke (a subscriber writes out what you are typing on the label below).
Feel free to contact me, Ephraim Tekle (@genzeb), if you need additional help integrating Tolo into your project.