Skip to content

Latest commit

 

History

History
40 lines (32 loc) · 2.3 KB

README-CFSTREAM.md

File metadata and controls

40 lines (32 loc) · 2.3 KB
Raw

Cocoapods

gRPC Objective-C with CFStream

gRPC now provides the option to use Apple's CFStream API (rather than TCP sockets) for networking. Using CFStream resolves a bunch of network connectivity transition issues (see the doc for more information).

CFStream integration is now in experimental state. You will need explicit opt-in to use it to get the benefits of resolving the issues above. We expect to make CFStream the default networking interface that gRPC uses when it is ready for production.

As of v1.21.0, CFStream integration is now the default networking stack being used by gRPC Objective-C on iOS layer. You get to use it automatically without special configuration needed. See below on how to disable CFStream in case of problem.

As of v1.23.0, CFStream is enabled by default on iOS for all wrapped languages. See below on how to disable CFStream in case of a problem.

Usage

If you use gRPC on iOS, CFStream is on automatically. If you use it on other platforms, you can turn it on with macro GRPC_CFSTREAM=1 for the pod 'gRPC-Core' and 'gRPC'. In case of problem and you want to disable CFStream on iOS, you can set environment variable "grpc_cfstream=0".

Caveats

It is known to us that the CFStream API has some bug (FB6162039) which will cause gRPC's CFStream networking layer to stall occasionally. The issue mostly occur on MacOS systems (including iOS simulators on MacOS); iOS may be affected too but we have not seen issue there. gRPC provides a workaround to this problem with an alternative poller based on CFRunLoop. The poller can be enabled by setting environment variable GRPC_CFSTREAM_RUN_LOOP=1. Note that the poller is a client side only poller that does not support running a server on it. That means if an app opts in to the CFRunLoop-based poller, the app cannot host a gRPC server (gRPC Objective-C does not support running a server but other languages running on iOS do support it).

Notes

  • Currently we do not support platforms other than iOS, although it is likely that this integration can run on MacOS targets with Apple's compiler.
  • Let us know if you meet any issue by filing issue and ping @stanleycheung.