public final class RedisPubSubHandler
extension RedisPubSubHandler: RemovableChannelHandler
extension RedisPubSubHandler: ChannelInboundHandler
extension RedisPubSubHandler: ChannelOutboundHandler

A channel handler that stores a map of closures and channel or pattern names subscribed to in Redis using Pub/Sub.

These RedisPubSubMessageReceiver closures are added and removed using methods directly on an instance of this handler.

When a receiver is added or removed, the handler will send the appropriate subscribe or unsubscribe message to Redis so that the connection reflects the local Channel state.


This handler is designed to be placed before a RedisCommandHandler so that it can intercept Pub/Sub messages and dispatch them to the appropriate receiver.

If a response is not in the Pub/Sub message format as specified by Redis, then it is treated as a normal Redis command response and sent further into the pipeline so that eventually a RedisCommandHandler can process it.


This handler is what is defined as a “transparent” NIO.ChannelOutboundHandler in that it does absolutely nothing except forward outgoing commands in the pipeline.

The reason why this handler needs to conform to this protocol at all, is that subscribe and unsubscribe commands are executed outside of a normal NIO.Channel.write(_:) cycle, as message receivers aren’t command arguments and need to be stored.

All of this is outside the responsibility of the RedisCommandHandler, so the RedisPubSubHandler uses its own NIO.ChannelHandlerContext being before the command handler to short circuit the pipeline.


As a connection can move in and out of “PubSub mode”, this handler is can be added and removed from a NIO.ChannelPipeline as needed.

When the handler has received a removeHandler(context:removalToken:) request, it will remove itself immediately.

  • Declaration


    public init(eventLoop: EventLoop, initialSubscriptionQueueCapacity queueCapacity: Int = 3)



    The event loop the NIO.Channel that this handler was added to is bound to.


    The initial capacity of queues used for processing subscription changes. The initial value is 3.

    Unless you are subscribing and unsubscribing from a large volume of channels or patterns at a single time, such as a single SUBSCRIBE call, you do not need to modify this value.

  • Registers the provided subscription message receiver to receive messages from the specified subscription target.


    Any previously registered receiver will be replaced and not notified.



    public func addSubscription(
        for target: RedisSubscriptionTarget,
        messageReceiver receiver: @escaping RedisSubscriptionMessageReceiver,
        onSubscribe subscribeHandler: RedisSubscriptionChangeHandler?,
        onUnsubscribe unsubscribeHandler: RedisSubscriptionChangeHandler?
    ) -> EventLoopFuture<Int>



    The channels or patterns that the receiver should receive messages for.


    The closure that receives any future pub/sub messages.


    An optional closure to invoke when the subscription first becomes active.


    An optional closure to invoke when the subscription becomes inactive.

    Return Value

    A NIO.EventLoopFuture that resolves the number of subscriptions the client has after the subscription has been added.

  • Removes the provided target as a subscription, stopping future messages from being received.



    public func removeSubscription(for target: RedisSubscriptionTarget) -> EventLoopFuture<Int>



    The channel or pattern that a receiver should be removed for.

    Return Value

    A NIO.EventLoopFuture that resolves the number of subscriptions the client has after the subscription has been removed.