gproc_ps.md 8.7 KB
#Module gproc_ps#
Gproc Publish/Subscribe patterns This module implements a few convenient functions for publish/subscribe.
Authors: Ulf Wiger (ulf@wiger.net).
##Description##
Publish/subscribe with Gproc relies entirely on gproc properties and counters. This makes for a very concise implementation, as the monitoring of subscribers and removal of subscriptions comes for free with Gproc.Using this module instead of rolling your own (which is easy enough) brings the benefit of consistency, in tracing and debugging. The implementation can also serve to illustrate how to use gproc properties and counters to good effect.
##Data Types##
###event()##
event() = any()
###msg()##
msg() = any()
###scope()##
scope() = l | g
###status()##
status() = 1 | 0
##Function Index##
| create_single/2 | Creates a single-shot subscription entry for Event. |
| delete_single/2 | Deletes the single-shot subscription for Event. |
| disable_single/2 | Disables the single-shot subscription for Event. |
| enable_single/2 | Enables the single-shot subscription for Event. |
| list_singles/2 | Lists all single-shot subscribers of Event, together with their status. |
| list_subs/2 | List the pids of all processes subscribing to Event |
| notify_single_if_true/4 | Create/enable a single subscription for event; notify at once if F() -> true. |
| publish/3 | Publish the message Msg to all subscribers of Event |
| subscribe/2 | Subscribe to events of type Event |
| tell_singles/3 | Publish Msg to all single-shot subscribers of Event |
| unsubscribe/2 | Remove subscribtion created using subscribe(Scope, Event) |
##Function Details##
###create_single/2##
create_single(Scope::scope(), Event::event()) -> true
Creates a single-shot subscription entry for Event
Single-shot subscriptions behave similarly to the {active,once} property of sockets.
Once a message has been published, the subscription is disabled, and no more messages
will be delivered to the subscriber unless the subscription is re-enabled using
enable_single/2.
The function creates a gproc counter entry, {c,Scope,{gproc_ps_event,Event}}, which
will have either of the values 0 (disabled) or 1 (enabled). Initially, the value
is 1, meaning the subscription is enabled.Counters are used in this case, since they can be atomically updated by both the
subscriber (owner) and publisher. The publisher sets the counter value to 0 as soon
as it has delivered a message.
###delete_single/2##
delete_single(Scope::scope(), Event::event()) -> true
Deletes the single-shot subscription for EventThis function deletes the counter entry representing the single-shot description. An exception will be raised if there is no such subscription.
###disable_single/2##
disable_single(Scope::scope(), Event::event()) -> integer()
Disables the single-shot subscription for Event
This function changes the value of the corresponding gproc counter to 0 (disabled).
The subscription remains (e.g. for debugging purposes), but with a 'disabled' status. This function is insensitive to concurrency, using 'wrapping' ets counter update ops. This guarantees that the counter will have either the value 1 or 0, depending on which update happened last.The return value indicates the previous status.
###enable_single/2##
enable_single(Scope::scope(), Event::event()) -> integer()
Enables the single-shot subscription for Event
This function changes the value of the corresponding gproc counter to 1 (enabled).
After enabling, the subscriber will receive the next message published for Event,
after which the subscription is automatically disabled.
This function is insensitive to concurrency, using 'wrapping' ets counter update ops. This guarantees that the counter will have either the value 1 or 0, depending on which update happened last.The return value indicates the previous status.
###list_singles/2##
list_singles(Scope::scope(), Event::event()) -> [{pid(), status()}]
Lists all single-shot subscribers of Event, together with their status
###list_subs/2##
list_subs(Scope::scope(), Event::event()) -> [pid()]
List the pids of all processes subscribing to EventThis function uses gproc:select/2 to find all properties indicating a subscription.
###notify_single_if_true/4##
notify_single_if_true(Scope::scope(), Event::event(), F::fun(() -> boolean()), Msg::msg()) -> ok
Create/enable a single subscription for event; notify at once if F() -> trueThis function is a convenience function, wrapping a single-shot pub/sub around a
user-provided boolean test. Msg should be what the publisher will send later, if the
immediate test returns false.
###publish/3##
publish(Scope::scope(), Event::event(), Msg::msg()) -> ok
Publish the message Msg to all subscribers of Event
The message delivered to each subscriber will be of the form:
{gproc_ps_event, Event, Msg}The function uses gproc:send/2 to send a message to all processes which have a
property {p,Scope,{gproc_ps_event,Event}}.
###subscribe/2##
subscribe(Scope::scope(), Event::event()) -> true
Subscribe to events of type Event
Any messages published with gproc_ps:publish(Scope, Event, Msg) will be delivered to
the current process, along with all other subscribers.This function creates a property, {p,Scope,{gproc_ps_event,Event}}, which can be
searched and displayed for debugging purposes.
###tell_singles/3##
tell_singles(Scope::scope(), Event::event(), Msg::msg()) -> [pid()]
Publish Msg to all single-shot subscribers of Event
The subscriber status of each active subscriber is changed to 0 (disabled) before
delivering the message. This reduces the risk that two different processes will be able
to both deliver a message before disabling the subscribers. This could happen if the
context switch happens just after the select operation (finding the active subscribers)
and before the process is able to update the counters. In this case, it is possible
that more than one can be delivered.The way to prevent this from happening is to ensure that only one process publishes
for Event.
###unsubscribe/2##
unsubscribe(Scope::scope(), Event::event()) -> true
Remove subscribtion created using subscribe(Scope, Event)This removes the property created through subscribe/2.