From e7339788851b6bf1cf13d47df86db4f845081d0c Mon Sep 17 00:00:00 2001 From: Ulf Wiger Date: Fri, 23 Feb 2024 20:33:51 +0100 Subject: [PATCH] Add some documentation of remote ps API --- doc/gproc_ps.md | 38 ++++++++++++++++++++++++++++++++------ src/gproc_ps.erl | 20 +++++++++++++++++++- 2 files changed, 51 insertions(+), 7 deletions(-) diff --git a/doc/gproc_ps.md b/doc/gproc_ps.md index 6627883..4198406 100644 --- a/doc/gproc_ps.md +++ b/doc/gproc_ps.md @@ -93,7 +93,7 @@ status() = 1 | 0 ## Function Index ## -
change_cond/3Change the condition specification of an existing subscription.
change_cond_remote/3
create_single/2Creates a single-shot subscription entry for Event.
create_single_remote/2
delete_single/2Deletes the single-shot subscription for Event.
delete_single_remote/2
disable_single/2Disables the single-shot subscription for Event.
disable_single_remote/2
enable_single/2Enables the single-shot subscription for Event.
enable_single_remote/2
list_singles/2Lists all single-shot subscribers of Event, together with their status.
list_subs/2List the pids of all processes subscribing to Event
notify_single_if_true/4Create/enable a single subscription for event; notify at once if F() -> true.
publish/3Publish the message Msg to all subscribers of Event
publish_cond/3Publishes the message Msg to conditional subscribers of Event
subscribe/2Subscribe to events of type Event
subscribe_cond/3Subscribe conditionally to events of type Event
subscribe_cond_remote/3
subscribe_remote/2Subscribe from a remote node.
tell_singles/3Publish Msg to all single-shot subscribers of Event
unsubscribe/2Remove subscribtion created using subscribe(Scope, Event)
unsubscribe_remote/2
+
change_cond/3Change the condition specification of an existing subscription.
change_cond_remote/3Change the condition spec of a subscription created from a remote node.
create_single/2Creates a single-shot subscription entry for Event.
create_single_remote/2Create a local single-shot subscription from a remote node.
delete_single/2Deletes the single-shot subscription for Event.
delete_single_remote/2Delete a single-shot subscription created from a remote node.
disable_single/2Disables the single-shot subscription for Event.
disable_single_remote/2Disable a single-shot subscription created from a remote node.
enable_single/2Enables the single-shot subscription for Event.
enable_single_remote/2Enable a single-shot subscription created from a remote node.
list_singles/2Lists all single-shot subscribers of Event, together with their status.
list_subs/2List the pids of all processes subscribing to Event
notify_single_if_true/4Create/enable a single subscription for event; notify at once if F() -> true.
publish/3Publish the message Msg to all subscribers of Event
publish_cond/3Publishes the message Msg to conditional subscribers of Event
subscribe/2Subscribe to events of type Event
subscribe_cond/3Subscribe conditionally to events of type Event
subscribe_cond_remote/3Subscribe conditionally from a remote node.
subscribe_remote/2Subscribe from a remote node.
tell_singles/3Publish Msg to all single-shot subscribers of Event
unsubscribe/2Remove subscription created using subscribe(Scope, Event)
unsubscribe_remote/2Remove subscription created from a remote node.
@@ -128,6 +128,8 @@ change_cond_remote(Node::node(), Event::event(), Spec:
+Change the condition spec of a subscription created from a remote node + ### create_single/2 ### @@ -156,7 +158,12 @@ as it has delivered a message. ### create_single_remote/2 ### -`create_single_remote(Node, Event) -> any()` +

+create_single_remote(Node::node(), Event::event()) -> true
+
+
+ +Create a local single-shot subscription from a remote node @@ -176,7 +183,12 @@ An exception will be raised if there is no such subscription. ### delete_single_remote/2 ### -`delete_single_remote(Node, Event) -> any()` +

+delete_single_remote(Node::node(), Event::event()) -> true
+
+
+ +Delete a single-shot subscription created from a remote node @@ -202,7 +214,12 @@ The return value indicates the previous status. ### disable_single_remote/2 ### -`disable_single_remote(Node, Event) -> any()` +

+disable_single_remote(Node::node(), Event::event()) -> status()
+
+
+ +Disable a single-shot subscription created from a remote node @@ -230,7 +247,12 @@ The return value indicates the previous status. ### enable_single_remote/2 ### -`enable_single_remote(Node, Event) -> any()` +

+enable_single_remote(Node::node(), Event::event()) -> status()
+
+
+ +Enable a single-shot subscription created from a remote node @@ -370,6 +392,8 @@ subscribe_cond_remote(Node::node(), Event::event(), Sp
+Subscribe conditionally from a remote node + ### subscribe_remote/2 ### @@ -414,7 +438,7 @@ unsubscribe(Scope::scope(), Event::event()) ->
+Remove subscription created from a remote node + diff --git a/src/gproc_ps.erl b/src/gproc_ps.erl index ae532ff..614aca1 100644 --- a/src/gproc_ps.erl +++ b/src/gproc_ps.erl @@ -135,6 +135,8 @@ subscribe_cond(Scope, Event, Spec) when Scope==l; Scope==g -> gproc:reg({p,Scope,{?ETag, Event}}, Spec). -spec subscribe_cond_remote(node(), event(), cond_spec()) -> true. +%% @doc Subscribe conditionally from a remote node +%% @end subscribe_cond_remote(Node, Event, Spec) when is_atom(Node) -> _ = case Spec of undefined -> ok; @@ -159,6 +161,8 @@ change_cond(Scope, Event, Spec) when Scope==l; Scope==g -> gproc:set_value({p,Scope,{?ETag, Event}}, Spec). -spec change_cond_remote(node(), event(), cond_spec()) -> true. +%% @doc Change the condition spec of a subscription created from a remote node +%% @end change_cond_remote(Node, Event, Spec) -> _ = validate_spec(Spec), gproc:set_value_remote(Node, {p,l,{?ETag, Event}}, Spec). @@ -171,7 +175,7 @@ validate_spec(Spec) -> end. -spec unsubscribe(scope(), event()) -> true. -%% @doc Remove subscribtion created using `subscribe(Scope, Event)' +%% @doc Remove subscription created using `subscribe(Scope, Event)' %% %% This removes the property created through `subscribe/2'. %% @end @@ -179,6 +183,8 @@ unsubscribe(Scope, Event) when Scope==l; Scope==g -> gproc:unreg({p,Scope,{?ETag, Event}}). -spec unsubscribe_remote(node(), event()) -> true. +%% @doc Remove subscription created from a remote node +%% @end unsubscribe_remote(Node, Event) -> gproc:unreg_remote(Node, {p, l, {?ETag, Event}}). @@ -292,16 +298,28 @@ enable_single(Scope, Event) when Scope==l; Scope==g -> [Prev,1] = gproc:update_counter({c,Scope,{?ETag,Event}}, [0, {1, 1, 1}]), Prev. +-spec create_single_remote(node(), event()) -> true. +%% @doc Create a local single-shot subscription from a remote node +%% @end create_single_remote(Node, Event) -> gproc:reg_remote(Node, {c,l,{?ETag, Event}}, 1). +-spec delete_single_remote(node(), event()) -> true. +%% @doc Delete a single-shot subscription created from a remote node +%% @end delete_single_remote(Node, Event) -> gproc:unreg_remote(Node, {c,l,{?ETag, Event}}). +-spec disable_single_remote(node(), event()) -> status(). +%% @doc Disable a single-shot subscription created from a remote node +%% @end disable_single_remote(Node, Event) -> [Prev,0] = gproc:update_counter_remote(Node, {c,l,{?ETag,Event}}, [0, {-1,0,0}]), Prev. +-spec enable_single_remote(node(), event()) -> status(). +%% @doc Enable a single-shot subscription created from a remote node +%% @end enable_single_remote(Node, Event) -> [Prev,1] = gproc:update_counter_remote(Node, {c,l,{?ETag,Event}}, [0, {1,1,1}]), Prev.