src/objective-c/README-CFSTREAM.md

   1 [![Cocoapods](https://img.shields.io/cocoapods/v/gRPC.svg)](https://cocoapods.org/pods/gRPC)
   2 # gRPC Objective-C with CFStream
   3
   4 gRPC now provides the option to use Apple's CFStream API (rather than TCP
   5 sockets) for networking. Using CFStream resolves a bunch of network connectivity transition issues
   6 (see the [doc](https://github.com/grpc/grpc/blob/master/src/objective-c/NetworkTransitionBehavior.md)
   7 for more information).
   8
   9 <s>CFStream integration is now in experimental state. You will need explicit opt-in to use it to get
  10 the benefits of resolving the issues above. We expect to make CFStream the default networking
  11 interface that gRPC uses when it is ready for production.</s>
  12
  13 As of v1.21.0, CFStream integration is now the default networking stack being used by gRPC
  14 Objective-C on iOS layer. You get to use it automatically without special configuration needed. See
  15 below on how to disable CFStream in case of problem.
  16
  17 As of v1.23.0, CFStream is enabled by default on iOS for all wrapped languages. See below on how to
  18 disable CFStream in case of a problem.
  19
  20 ## Usage
  21 If you use gRPC on iOS, CFStream is on automatically. If you use it on other
  22 platforms, you can turn it on with macro `GRPC_CFSTREAM=1` for the pod 'gRPC-Core' and 'gRPC'. In
  23 case of problem and you want to disable CFStream on iOS, you can set environment variable
  24 "grpc\_cfstream=0".
  25
  26 ## Caveats
  27 It is known to us that the CFStream API has some bug (FB6162039) which will cause gRPC's CFStream
  28 networking layer to stall occasionally. The issue mostly occur on MacOS systems (including iOS
  29 simulators on MacOS); iOS may be affected too but we have not seen issue there. gRPC provides a
  30 workaround to this problem with an alternative poller based on CFRunLoop. The poller can be enabled
  31 by setting environment variable `GRPC_CFSTREAM_RUN_LOOP=1`. Note that the poller is a client side
  32 only poller that does not support running a server on it. That means if an app opts in to the
  33 CFRunLoop-based poller, the app cannot host a gRPC server (gRPC Objective-C does not support running
  34 a server but other languages running on iOS do support it).
  35
  36 ## Notes
  37
  38 - Currently we do not support platforms other than iOS, although it is likely that this integration
  39   can run on MacOS targets with Apple's compiler.
  40 - Let us know if you meet any issue by filing issue and ping @stanleycheung.