diff --git a/src/pages/docs/api/realtime-sdk/channels.mdx b/src/pages/docs/api/realtime-sdk/channels.mdx index 595f4534cd..e6fb515242 100644 --- a/src/pages/docs/api/realtime-sdk/channels.mdx +++ b/src/pages/docs/api/realtime-sdk/channels.mdx @@ -67,15 +67,15 @@ Derived channels enables you to subscribe to a filtered subset of messages on a -Releases a [Channel](#properties) object, deleting it from the local SDK client instance and enabling it to be garbage collected. It also removes any listeners associated with the channel on this specific client instance. +Releases all SDK-held references to a [Channel](#properties) object, enabling it to be garbage collected. It can be useful for applications that work with a continually changing set of channels on a single client and need to avoid unbounded memory growth; if this does not describe your application, don't call it. -This method only affects the local client-side representation of the channel. The channel itself on the Ably platform is not deleted or changed, and other client instances (in the same or different processes) are unaffected. Any listeners attached through other client instances remain active. + -After releasing a channel, calling `channels.get(channelName)` will create a fresh channel object with no listeners. If the channel was attached before being released, the new channel object will be in the `initialized` state, not `attached`. +This method only affects the local client-side representation of the channel. The channel itself on the Ably platform is not deleted or changed, and other client instances (in the same or different processes) are unaffected. -If using a singleton client pattern with multiple execution contexts, be cautious when calling `release` as it will affect all parts of your application using that client instance. Consider using `unsubscribe` for specific listeners instead. - -**Note**: To release a channel, the [channel state](/docs/channels/states) must be `initialized`, `detached` or `failed`. +Channels not already in the `initialized`, `detached`, or `failed` [state](/docs/channels/states) are detached before release. After release, calling `channels.get(channelName)` returns a fresh channel object in the `initialized` state. ## Channel diff --git a/src/pages/docs/api/rest-sdk/channels.mdx b/src/pages/docs/api/rest-sdk/channels.mdx index d5e009f83c..6695a70758 100644 --- a/src/pages/docs/api/rest-sdk/channels.mdx +++ b/src/pages/docs/api/rest-sdk/channels.mdx @@ -56,11 +56,15 @@ Creates a new [Channel](#properties) object if none for the channel exists, or r -Releases a [Channel](#properties) object, deleting it from the local SDK client instance and enabling it to be garbage collected. +Releases all SDK-held references to a [Channel](#properties) object, enabling it to be garbage collected. It can be useful for applications that work with a continually changing set of channels on a single client and need to avoid unbounded memory growth; if this does not describe your application, don't call it. + + This method only affects the local client-side representation of the channel. The channel itself on the Ably platform is not deleted or changed, and other client instances (in the same or different processes) are unaffected. -After releasing a channel, calling `channels.get(channelName)` will create a fresh channel object. If using a singleton REST client pattern with multiple execution contexts, be cautious when calling `release` as it will affect all parts of your application using that client instance. Subsequent publish operations on the same channel name will require obtaining a new channel object. +After release, calling `channels.get(channelName)` returns a fresh channel object. ## Channel