From 66752cdac8bca915177e7fbbf107828c8ac6f1e0 Mon Sep 17 00:00:00 2001 From: Shachar Langbeheim Date: Mon, 2 Dec 2024 20:51:31 +0200 Subject: [PATCH] Clarify RESP3 subscription documentation. This hopefully helps clarify some of the issues raised in https://github.com/redis-rs/redis-rs/issues/1435 --- redis/src/aio/connection_manager.rs | 18 +++++++++++++++++- redis/src/aio/multiplexed_connection.rs | 14 ++++++++++++++ redis/src/client.rs | 4 +++- 3 files changed, 34 insertions(+), 2 deletions(-) diff --git a/redis/src/aio/connection_manager.rs b/redis/src/aio/connection_manager.rs index 90c46c078..53eee58ce 100644 --- a/redis/src/aio/connection_manager.rs +++ b/redis/src/aio/connection_manager.rs @@ -93,7 +93,9 @@ impl ConnectionManagerConfig { self } - /// Sets sender channel for push values. Will fail client creation if the connection isn't configured for RESP3 communications. + /// Sets sender channel for push values. + /// + /// This will fail client creation if the connection isn't configured for RESP3 communications via the [RedisConnectionInfo::protocol] field. pub fn set_push_sender(mut self, sender: AsyncPushSender) -> Self { self.push_sender = Some(sender); self @@ -391,6 +393,11 @@ impl ConnectionManager { } /// Subscribes to a new channel. + /// + /// Updates from the sender will be sent on the push sender that was passed to the manager. + /// If the manager was configured without a push sender, the connection won't be able to pass messages back to the user.. + /// + /// This method is only available when the connection is using RESP3 protocol, and will return an error otherwise. /// It should be noted that the subscription will be removed on a disconnect and must be re-subscribed. pub async fn subscribe(&mut self, channel_name: impl ToRedisArgs) -> RedisResult<()> { check_resp3!(self.client.connection_info.redis.protocol); @@ -401,6 +408,8 @@ impl ConnectionManager { } /// Unsubscribes from channel. + /// + /// This method is only available when the connection is using RESP3 protocol, and will return an error otherwise. pub async fn unsubscribe(&mut self, channel_name: impl ToRedisArgs) -> RedisResult<()> { check_resp3!(self.client.connection_info.redis.protocol); let mut cmd = cmd("UNSUBSCRIBE"); @@ -410,6 +419,11 @@ impl ConnectionManager { } /// Subscribes to a new channel with pattern. + /// + /// Updates from the sender will be sent on the push sender that was passed to the manager. + /// If the manager was configured without a push sender, the manager won't be able to pass messages back to the user.. + /// + /// This method is only available when the connection is using RESP3 protocol, and will return an error otherwise. /// It should be noted that the subscription will be removed on a disconnect and must be re-subscribed. pub async fn psubscribe(&mut self, channel_pattern: impl ToRedisArgs) -> RedisResult<()> { check_resp3!(self.client.connection_info.redis.protocol); @@ -420,6 +434,8 @@ impl ConnectionManager { } /// Unsubscribes from channel pattern. + /// + /// This method is only available when the connection is using RESP3 protocol, and will return an error otherwise. pub async fn punsubscribe(&mut self, channel_pattern: impl ToRedisArgs) -> RedisResult<()> { check_resp3!(self.client.connection_info.redis.protocol); let mut cmd = cmd("PUNSUBSCRIBE"); diff --git a/redis/src/aio/multiplexed_connection.rs b/redis/src/aio/multiplexed_connection.rs index 8db4b1aa8..931b92a14 100644 --- a/redis/src/aio/multiplexed_connection.rs +++ b/redis/src/aio/multiplexed_connection.rs @@ -592,6 +592,11 @@ impl ConnectionLike for MultiplexedConnection { impl MultiplexedConnection { /// Subscribes to a new channel. + /// + /// Updates from the sender will be sent on the push sender that was passed to the connection. + /// If the connection was configured without a push sender, the connection won't be able to pass messages back to the user.. + /// + /// This method is only available when the connection is using RESP3 protocol, and will return an error otherwise. pub async fn subscribe(&mut self, channel_name: impl ToRedisArgs) -> RedisResult<()> { check_resp3!(self.protocol); let mut cmd = cmd("SUBSCRIBE"); @@ -601,6 +606,8 @@ impl MultiplexedConnection { } /// Unsubscribes from channel. + /// + /// This method is only available when the connection is using RESP3 protocol, and will return an error otherwise. pub async fn unsubscribe(&mut self, channel_name: impl ToRedisArgs) -> RedisResult<()> { check_resp3!(self.protocol); let mut cmd = cmd("UNSUBSCRIBE"); @@ -610,6 +617,11 @@ impl MultiplexedConnection { } /// Subscribes to a new channel with pattern. + /// + /// Updates from the sender will be sent on the push sender that was passed to the connection. + /// If the connection was configured without a push sender, the connection won't be able to pass messages back to the user.. + /// + /// This method is only available when the connection is using RESP3 protocol, and will return an error otherwise. pub async fn psubscribe(&mut self, channel_pattern: impl ToRedisArgs) -> RedisResult<()> { check_resp3!(self.protocol); let mut cmd = cmd("PSUBSCRIBE"); @@ -619,6 +631,8 @@ impl MultiplexedConnection { } /// Unsubscribes from channel pattern. + /// + /// This method is only available when the connection is using RESP3 protocol, and will return an error otherwise. pub async fn punsubscribe(&mut self, channel_pattern: impl ToRedisArgs) -> RedisResult<()> { check_resp3!(self.protocol); let mut cmd = cmd("PUNSUBSCRIBE"); diff --git a/redis/src/client.rs b/redis/src/client.rs index a3a0a8397..e6758c0f7 100644 --- a/redis/src/client.rs +++ b/redis/src/client.rs @@ -186,7 +186,9 @@ impl AsyncConnectionConfig { self } - /// Sets sender channel for push values. Will fail client creation if the connection isn't configured for RESP3 communications. + /// Sets sender channel for push values. + /// + /// This will fail client creation if the connection isn't configured for RESP3 communications via the [RedisConnectionInfo::protocol] field. pub fn set_push_sender(mut self, sender: AsyncPushSender) -> Self { self.push_sender = Some(sender); self