added gproc_ps:change_cond/3

doc/gproc_ps.md

@@ -67,14 +67,35 @@ counters to good effect.
 ##Function Index##
 
 
-<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#create_single-2">create_single/2</a></td><td>Creates a single-shot subscription entry for Event.</td></tr><tr><td valign="top"><a href="#delete_single-2">delete_single/2</a></td><td>Deletes the single-shot subscription for Event.</td></tr><tr><td valign="top"><a href="#disable_single-2">disable_single/2</a></td><td>Disables the single-shot subscription for Event.</td></tr><tr><td valign="top"><a href="#enable_single-2">enable_single/2</a></td><td>Enables the single-shot subscription for Event.</td></tr><tr><td valign="top"><a href="#list_singles-2">list_singles/2</a></td><td>Lists all single-shot subscribers of Event, together with their status.</td></tr><tr><td valign="top"><a href="#list_subs-2">list_subs/2</a></td><td>List the pids of all processes subscribing to <code>Event</code></td></tr><tr><td valign="top"><a href="#notify_single_if_true-4">notify_single_if_true/4</a></td><td>Create/enable a single subscription for event; notify at once if F() -> true.</td></tr><tr><td valign="top"><a href="#publish-3">publish/3</a></td><td>Publish the message <code>Msg</code> to all subscribers of <code>Event</code></td></tr><tr><td valign="top"><a href="#publish_cond-3">publish_cond/3</a></td><td>Publishes the message <code>Msg</code> to conditional subscribers of <code>Event</code></td></tr><tr><td valign="top"><a href="#subscribe-2">subscribe/2</a></td><td>Subscribe to events of type <code>Event</code></td></tr><tr><td valign="top"><a href="#subscribe_cond-3">subscribe_cond/3</a></td><td>Subscribe conditionally to events of type <code>Event</code></td></tr><tr><td valign="top"><a href="#tell_singles-3">tell_singles/3</a></td><td>Publish <code>Msg</code> to all single-shot subscribers of <code>Event</code></td></tr><tr><td valign="top"><a href="#unsubscribe-2">unsubscribe/2</a></td><td>Remove subscribtion created using <code>subscribe(Scope, Event)</code></td></tr></table>
+<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#change_cond-3">change_cond/3</a></td><td>Change the condition specification of an existing subscription.</td></tr><tr><td valign="top"><a href="#create_single-2">create_single/2</a></td><td>Creates a single-shot subscription entry for Event.</td></tr><tr><td valign="top"><a href="#delete_single-2">delete_single/2</a></td><td>Deletes the single-shot subscription for Event.</td></tr><tr><td valign="top"><a href="#disable_single-2">disable_single/2</a></td><td>Disables the single-shot subscription for Event.</td></tr><tr><td valign="top"><a href="#enable_single-2">enable_single/2</a></td><td>Enables the single-shot subscription for Event.</td></tr><tr><td valign="top"><a href="#list_singles-2">list_singles/2</a></td><td>Lists all single-shot subscribers of Event, together with their status.</td></tr><tr><td valign="top"><a href="#list_subs-2">list_subs/2</a></td><td>List the pids of all processes subscribing to <code>Event</code></td></tr><tr><td valign="top"><a href="#notify_single_if_true-4">notify_single_if_true/4</a></td><td>Create/enable a single subscription for event; notify at once if F() -> true.</td></tr><tr><td valign="top"><a href="#publish-3">publish/3</a></td><td>Publish the message <code>Msg</code> to all subscribers of <code>Event</code></td></tr><tr><td valign="top"><a href="#publish_cond-3">publish_cond/3</a></td><td>Publishes the message <code>Msg</code> to conditional subscribers of <code>Event</code></td></tr><tr><td valign="top"><a href="#subscribe-2">subscribe/2</a></td><td>Subscribe to events of type <code>Event</code></td></tr><tr><td valign="top"><a href="#subscribe_cond-3">subscribe_cond/3</a></td><td>Subscribe conditionally to events of type <code>Event</code></td></tr><tr><td valign="top"><a href="#tell_singles-3">tell_singles/3</a></td><td>Publish <code>Msg</code> to all single-shot subscribers of <code>Event</code></td></tr><tr><td valign="top"><a href="#unsubscribe-2">unsubscribe/2</a></td><td>Remove subscribtion created using <code>subscribe(Scope, Event)</code></td></tr></table>
 
 
 <a name="functions"></a>
 
 ##Function Details##
 
-<a name="create_single-2"></a>
+<a name="change_cond-3"></a>
+
+###change_cond/3##
+
+
+<pre>change_cond(Scope::<a href="#type-scope">scope()</a>, Event::<a href="#type-event">event()</a>, Spec::undefined | <a href="ets.md#type-match_spec">ets:match_spec()</a>) -> true</pre>
+<br></br>
+
+
+
+
+Change the condition specification of an existing subscription.
+
+
+
+This function atomically changes the condition spec of an existing
+subscription (see [`subscribe_cond/3`](#subscribe_cond-3)). An exception is raised if
+the subscription doesn't already exist.
+
+Note that this function can also be used to change a conditional subscription
+to an unconditional one (by setting `Spec = undefined`), or a 'normal'
+subscription to a conditional one.<a name="create_single-2"></a>
 
 ###create_single/2##
 

src/gproc_ps.erl

@@ -36,6 +36,7 @@
 
 -export([subscribe/2,
 	 subscribe_cond/3,
+	 change_cond/3,
 	 unsubscribe/2,
 	 publish/3,
 	 publish_cond/3,
@@ -103,6 +104,26 @@ subscribe_cond(Scope, Event, Spec) when Scope==l; Scope==g ->
     end,
     gproc:reg({p,Scope,{?ETag, Event}}, Spec).
 
+-spec change_cond(scope(), event(), undefined | ets:match_spec()) -> true.
+%% @doc Change the condition specification of an existing subscription.
+%%
+%% This function atomically changes the condition spec of an existing
+%% subscription (see {@link subscribe_cond/3}). An exception is raised if
+%% the subscription doesn't already exist.
+%%
+%% Note that this function can also be used to change a conditional subscription
+%% to an unconditional one (by setting `Spec = undefined'), or a 'normal'
+%% subscription to a conditional one.
+%% @end
+change_cond(Scope, Event, Spec) when Scope==l; Scope==g ->
+    case Spec of
+	undefined -> ok;
+	[_|_] -> _ = ets:match_spec_compile(Spec);  % validation
+	_ -> error(badarg)
+    end,
+    gproc:set_value({p,Scope,{?ETag, Event}}, Spec).
+
+
 -spec unsubscribe(scope(), event()) -> true.
 %% @doc Remove subscribtion created using `subscribe(Scope, Event)'
 %%