include/ipc: Add method for unsubscribing an endpoint from topics

The IPC module does not provide a function for unsubscribing an
endpoint from a pubsub topic, forcing a script that wishes to
unsubscribe from a topic to close the endpoint and open a new one.

This commit adds the `ipc_endpoint_unsubscribe()' method to the IPC
module, allowing an endpoint to be unsubscribed from pubsub topics.

diff --git a/docs/ipc.md b/docs/ipc.md
index 2cda1bae91b607d5b3ce3870fecee541c7d6a13b..6c6796c98445f128c4c717815a3a54a9ea9b9570 100644 (file)
--- a/docs/ipc.md
+++ b/docs/ipc.md
@@ -27,6 +27,7 @@ sent by one module cannot be read by the other.
 | [ipc_endpoint_recv()](#ipc_endpoint_recv)                       | Receive a point-to-point or pub-sub message            |
 | [ipc_endpoint_send()](#ipc_endpoint_send)                       | Send a point-to-point message to another endpoint      |
 | [ipc_endpoint_subscribe()](#ipc_endpoint_subscribe)             | Subscribe an endpoint to a topic                       |
+| [ipc_endpoint_unsubscribe()](#ipc_endpoint_unsubscribe)         | Unsubscribe an endpoint from one or more topics        |
 | [ipc_get_root()](#ipc_get_root)                                 | Return the path to the IPC directory                   |
 | [ipc_msg_dump()](#ipc_msg_dump)                                 | Dump the contents of an IPC message to standard output |
 | [ipc_msg_get()](#ipc_msg_get)                                   | Extract data from an IPC message                       |
@@ -364,6 +365,41 @@ This function does not write to standard output.
 In case of an error, an error message is written to standard error.
 
 
+## ipc_endpoint_unsubscribe()
+
+Unsubscribe an endpoint from one or more topics
+
+### Synopsis
+
+    ipc_endpoint_unsubscribe "$endpoint" "${topics[@]}"
+
+### Description
+
+The `ipc_endpoint_unsubscribe()` function unsubscribes the endpoint referenced by `endpoint` from the
+topics passed in `topics`. If the call succeeded, the endpoint will no longer receive messages that
+were published on any of the topics. However, the endpoint will still receive messages that were
+already in its queue at the time when the topic was unsubscribed.
+
+### Return value
+
+| Return value | Meaning                                                 |
+|--------------|---------------------------------------------------------|
+| 0            | All unsubscribe operations were successful              |
+| 1            | The endpoint could not be unsubscribed from some topics |
+
+### Standard input
+
+This function does not read from standard input.
+
+### Standard output
+
+This function does not write to standard output.
+
+### Standard error
+
+In case of an error, an error message is written to standard error.
+
+
 ## ipc_get_root()
 
 Return the path to the IPC directory

diff --git a/include/ipc.sh b/include/ipc.sh
index 4d79232733bfe92958818f824d2e7803e1cf7f72..62f8dfe7c54c11d56c8ac065c64ebf05700fcb07 100644 (file)
--- a/include/ipc.sh
+++ b/include/ipc.sh
@@ -42,6 +42,7 @@ __init() {
                  "endpoint_send"            \
                  "endpoint_recv"            \
                  "endpoint_subscribe"       \
+                 "endpoint_unsubscribe"     \
                  "endpoint_publish"         \
                  "endpoint_foreach_message" \
 
@@ -641,6 +642,25 @@ _ipc_endpoint_topic_subscribe() {
        return 0
 }
 
+_ipc_endpoint_topic_unsubscribe() {
+       local endpoint="$1"
+       local topic="$2"
+
+       local root
+       local topicref
+       local endpointref
+
+       root=$(ipc_get_root)
+       topicref="$root/$endpoint/subscriptions/$topic"
+       endpointref="$root/pubsub/$topic/${endpoint//\//_}"
+
+       if ! rm -f "$topicref" "$endpointref"; then
+               return 1
+       fi
+
+       return 0
+}
+
 _ipc_endpoint_topic_get_subscribers() {
        local topic="$1"
 
@@ -685,6 +705,21 @@ ipc_endpoint_subscribe() {
        return 0
 }
 
+ipc_endpoint_unsubscribe() {
+       local endpoint="$1"
+       local topics=("${@:2}")
+
+       local topic
+
+       for topic in "${topics[@]}"; do
+               if ! _ipc_endpoint_topic_unsubscribe "$endpoint" "$topic"; then
+                       return 1
+               fi
+       done
+
+       return 0
+}
+
 ipc_endpoint_publish() {
        local endpoint="$1"
        local topic="$2"