New channel pool design

1 files changed, 62 insertions, 12 deletions

diff --git a/src/objective-c/GRPCClient/private/GRPCChannelPool.h b/src/objective-c/GRPCClient/private/GRPCChannelPool.h
index 48779c4449..887bd5f89f 100644
--- a/src/objective-c/GRPCClient/private/GRPCChannelPool.h
+++ b/src/objective-c/GRPCClient/private/GRPCChannelPool.h
@@ -27,7 +27,53 @@
 
 NS_ASSUME_NONNULL_BEGIN
 
+@protocol GRPCChannel;
 @class GRPCChannel;
+@class GRPCChannelPool;
+@class GRPCCompletionQueue;
+@class GRPCChannelConfiguration;
+
+/**
+ * Channel proxy that can be retained and automatically reestablish connection when the channel is
+ * disconnected.
+ */
+@interface GRPCPooledChannel : NSObject
+
+/**
+ * Initialize with an actual channel object \a channel and a reference to the channel pool.
+ */
+- (nullable instancetype)initWithChannelConfiguration:(GRPCChannelConfiguration *)channelConfiguration
+                                          channelPool:(GRPCChannelPool *)channelPool;
+
+
+/**
+ * Create a grpc core call object (grpc_call) from this channel. If channel is disconnected, get a
+ * new channel object from the channel pool.
+ */
+- (nullable grpc_call *)unmanagedCallWithPath:(NSString *)path
+                              completionQueue:(GRPCCompletionQueue *)queue
+                                  callOptions:(GRPCCallOptions *)callOptions;
+
+/**
+ * Return ownership and destroy the grpc_call object created by
+ * \a unmanagedCallWithPath:completionQueue:callOptions: and decrease channel refcount. If refcount
+ * of the channel becomes 0, return the channel object to channel pool.
+ */
+- (void)unrefUnmanagedCall:(grpc_call *)unmanagedCall;
+
+/**
+ * Force the channel to disconnect immediately.
+ */
+- (void)disconnect;
+
+// The following methods and properties are for test only
+
+/**
+ * Return the pointer to the real channel wrapped by the proxy.
+ */
+@property(atomic, readonly) GRPCChannel *wrappedChannel;
+
+@end
 
 /**
  * Manage the pool of connected channels. When a channel is no longer referenced by any call,
@@ -36,37 +82,41 @@ NS_ASSUME_NONNULL_BEGIN
 @interface GRPCChannelPool : NSObject
 
 /**
- * Get the singleton instance
+ * Get the global channel pool.
  */
 + (nullable instancetype)sharedInstance;
 
 /**
- * Return a channel with a particular configuration. If the channel does not exist, execute \a
- * createChannel then add it in the pool. If the channel exists, increase its reference count.
+ * Return a channel with a particular configuration. The channel may be a cached channel.
  */
-- (GRPCChannel *)channelWithHost:(NSString *)host callOptions:(GRPCCallOptions *)callOptions;
+- (GRPCPooledChannel *)channelWithHost:(NSString *)host callOptions:(GRPCCallOptions *)callOptions;
 
 /**
  * This method is deprecated.
  *
  * Destroy all open channels and close their connections.
  */
-+ (void)closeOpenConnections;
+- (void)closeOpenConnections;
 
 // Test-only methods below
 
 /**
- * Return a channel with a special destroy delay. If \a destroyDelay is 0, use the default destroy
- * delay.
+ * Get an instance of pool isolated from the global shared pool. This method is for test only.
+ * Global pool should be used in production.
+ */
+- (nullable instancetype)init;
+
+/**
+ * Simulate a network transition event and destroy all channels. This method is for internal and
+ * test only.
  */
-- (GRPCChannel *)channelWithHost:(NSString *)host
-                     callOptions:(GRPCCallOptions *)callOptions
-                    destroyDelay:(NSTimeInterval)destroyDelay;
+- (void)disconnectAllChannels;
 
 /**
- * Simulate a network transition event and destroy all channels.
+ * Set the destroy delay of channels. A channel should be destroyed if it stayed idle (no active
+ * call on it) for this period of time. This property is for test only.
  */
-- (void)destroyAllChannels;
+@property(atomic) NSTimeInterval destroyDelay;
 
 @end