z_notifier (zotonic_core v1.0.0-rc.17)

Simple implementation of an observer/notifier. Relays events to observers of that event. Also implements map and fold operations over the observers.

Summary

Functions

await(Notification, Context)

Subscribe once to a notification, detach after receiving the notification. After 5 seconds an error 'timeout' is returned.

await(Notification, Timeout, Context)

Subscribe once to a notification, detach after receiving the notification. After the timeout (in msec) an error 'timeout' is returned.

await_exact(Notification, Context)

await_exact(Notification, Timeout, Context)

detach(Event, Context)

Unsubscribe from an event.

detach(Event, OwnerPid, Site)

detach_all(Context)

Detach all observers and delete the event

detach_all(OwnerPid, Site)

first(Msg, Context)

Call all observers till one returns something else than undefined. If there are no observers then undefined is returned. The prototype of the observer is: f(Msg, Context)

foldl(Msg, Acc, Context)

Do a fold over all observers, prio 1 observers first. The prototype of the observer is: f(Msg, Acc, Context)

foldr(Msg, Acc, Context)

Do a fold over all observers, prio 1 observers last. The prototype of the observer is: f(Msg, Acc, Context)

get_observers(Context)

List all observers for all events for the site.

get_observers(Event, Site)

Return all observers for a particular event

map(Msg, Context)

Call all observers, return the list of answers. The prototype of the observer is: f(Msg, Context)

notify1(Msg, Context)

Async cast the event to the first observer. A process is forked in which the observer is called. If there is a database transaction then the notification is delayed till the end of the transaction. The prototype of the observer is: f(Msg, Context) -> void

notify(Msg, Context)

Async cast the event to all observers. A process is forked in which all observers are called. If there is a database transaction then the notification is delayed till the end of the transaction. The prototype of the observer is: f(Msg, Context) -> void

notify_queue(Context)

Send all delayed notify or notify1 notifications. This is used to delay notifications during a database transaction. When the transaction finishes all notifications are sent.

notify_queue_flush(Context)

Erase queued notifications. Useful if delayed notifications should not be sent, for example if the current database transaction rolled back. The queue is only flushed if there isn't a database transaction.

notify_sync(Msg, Context)

Sync cast the event to all observers. All observers are called in the current process. This is ideal for frequent notifications or notifications that need to be handled before processing can continue. The prototype of the observer is: f(Msg, Context) -> void

observe(Event, Observer, Context)

Subscribe to an event. Observer is a MFA or pid()

observe(Event, Observer, Priority, Context)

Subscribe to an event. Observer is a MFA or pid()

observe(Event, Observer, OwnerPid, Priority, Site)

Types

notification/0

-type notification() :: atom() | tuple().

Functions

await(Notification, Context)

-spec await(Notification, Context) ->
               {ok, notification()} | {ok, {pid(), reference()}, notification()} | {error, Reason}
               when Notification :: notification(), Context :: z:context(), Reason :: timeout.

Subscribe once to a notification, detach after receiving the notification. After 5 seconds an error 'timeout' is returned.

await(Notification, Timeout, Context)

-spec await(Notification, Timeout, Context) ->
               {ok, notification()} | {ok, {pid(), reference()}, notification()} | {error, Reason}
               when
                   Notification :: notification(),
                   Timeout :: pos_integer(),
                   Context :: z:context(),
                   Reason :: timeout.

Subscribe once to a notification, detach after receiving the notification. After the timeout (in msec) an error 'timeout' is returned.

await_exact(Notification, Context)

-spec await_exact(Notification, Context) ->
                     {ok, notification()} | {ok, {pid(), reference()}, notification()} | {error, Reason}
                     when Notification :: notification(), Context :: z:context(), Reason :: timeout.

await_exact(Notification, Timeout, Context)

-spec await_exact(Notification, Timeout, Context) ->
                     {ok, notification()} | {ok, {pid(), reference()}, notification()} | {error, Reason}
                     when
                         Notification :: notification(),
                         Timeout :: pos_integer(),
                         Context :: z:context(),
                         Reason :: timeout.

detach(Event, Context)

Unsubscribe from an event.

detach(Event, OwnerPid, Site)

detach_all(Context)

Detach all observers and delete the event

detach_all(OwnerPid, Site)

first(Msg, Context)

-spec first(Msg, Context) -> Result
               when Msg :: notification(), Context :: z:context(), Result :: undefined | term().

Call all observers till one returns something else than undefined. If there are no observers then undefined is returned. The prototype of the observer is: f(Msg, Context)

foldl(Msg, Acc, Context)

-spec foldl(Msg, Acc, Context) -> Result
               when Msg :: notification(), Context :: z:context(), Acc :: term(), Result :: term().

Do a fold over all observers, prio 1 observers first. The prototype of the observer is: f(Msg, Acc, Context)

foldr(Msg, Acc, Context)

-spec foldr(Msg, Acc, Context) -> Result
               when Msg :: notification(), Context :: z:context(), Acc :: term(), Result :: term().

Do a fold over all observers, prio 1 observers last. The prototype of the observer is: f(Msg, Acc, Context)

get_observers(Context)

-spec get_observers(z:context()) -> [{atom(), [{integer(), zotonic_notifier:observer()}]}].

List all observers for all events for the site.

get_observers(Event, Site)

Return all observers for a particular event

map(Msg, Context)

-spec map(Msg, Context) -> Result when Msg :: notification(), Context :: z:context(), Result :: [term()].

Call all observers, return the list of answers. The prototype of the observer is: f(Msg, Context)

notify1(Msg, Context)

-spec notify1(Msg, Context) -> ok | {error, Reason}
                 when Msg :: notification(), Context :: z:context(), Reason :: term().

notify(Msg, Context)

-spec notify(Msg, Context) -> ok | {error, Reason}
                when Msg :: notification(), Context :: z:context(), Reason :: term().

notify_queue(Context)

-spec notify_queue(Context) -> ok | {error, transaction} when Context :: z:context().

Send all delayed notify or notify1 notifications. This is used to delay notifications during a database transaction. When the transaction finishes all notifications are sent.

notify_queue_flush(Context)

-spec notify_queue_flush(Context) -> ok | {error, transaction} when Context :: z:context().

notify_sync(Msg, Context)

-spec notify_sync(Msg, Context) -> ok | {error, Reason}
                     when Msg :: notification(), Context :: z:context(), Reason :: term().

observe(Event, Observer, Context)

Subscribe to an event. Observer is a MFA or pid()

observe(Event, Observer, Priority, Context)

Subscribe to an event. Observer is a MFA or pid()

observe(Event, Observer, OwnerPid, Priority, Site)

-spec observe(zotonic_notifier:event(),
              zotonic_notifier:observer(),
              pid(),
              integer(),
              atom() | z:context()) ->
                 ok | {error, term()}.