Merge github.com:grpc/grpc into flow-like-lava-to-a-barnyard

Conflicts:
	src/core/surface/call.c
	src/core/transport/chttp2_transport.c
	src/core/transport/transport.h

1 files changed, 16 insertions, 6 deletions

diff --git a/src/core/iomgr/pollset_kick_posix.h b/src/core/iomgr/pollset_kick_posix.h
index b35c2cfbe0..77e32a8d51 100644
--- a/src/core/iomgr/pollset_kick_posix.h
+++ b/src/core/iomgr/pollset_kick_posix.h
@@ -37,6 +37,11 @@
 #include "src/core/iomgr/wakeup_fd_posix.h"
 #include <grpc/support/sync.h>
 
+/* pollset kicking allows breaking a thread out of polling work for
+   a given pollset.
+   writing a byte to a pipe is used as a posix-ly portable base
+   mechanism, and eventfds are utilized on Linux for better performance. */
+
 typedef struct grpc_kick_fd_info {
   grpc_wakeup_fd_info wakeup_fd;
   /* used for polling list and free list */
@@ -51,7 +56,8 @@ typedef struct grpc_pollset_kick_state {
   struct grpc_kick_fd_info fd_list;
 } grpc_pollset_kick_state;
 
-#define GRPC_POLLSET_KICK_GET_FD(kick_fd_info) GRPC_WAKEUP_FD_GET_READ_FD(&(kick_fd_info)->wakeup_fd)
+#define GRPC_POLLSET_KICK_GET_FD(kick_fd_info) \
+  GRPC_WAKEUP_FD_GET_READ_FD(&(kick_fd_info)->wakeup_fd)
 
 /* This is an abstraction around the typical pipe mechanism for waking up a
    thread sitting in a poll() style call. */
@@ -66,18 +72,22 @@ void grpc_pollset_kick_destroy(grpc_pollset_kick_state *kick_state);
  * applicable. Intended for testing. */
 void grpc_pollset_kick_global_init_fallback_fd(void);
 
-/* Must be called before entering poll(). If return value is -1, this consumed
+/* Must be called before entering poll(). If return value is NULL, this consumed
    an existing kick. Otherwise the return value is an FD to add to the poll set.
  */
-grpc_kick_fd_info *grpc_pollset_kick_pre_poll(grpc_pollset_kick_state *kick_state);
+grpc_kick_fd_info *grpc_pollset_kick_pre_poll(
+    grpc_pollset_kick_state *kick_state);
 
 /* Consume an existing kick. Must be called after poll returns that the fd was
    readable, and before calling kick_post_poll. */
-void grpc_pollset_kick_consume(grpc_pollset_kick_state *kick_state, grpc_kick_fd_info *fd_info);
+void grpc_pollset_kick_consume(grpc_pollset_kick_state *kick_state,
+                               grpc_kick_fd_info *fd_info);
 
 /* Must be called after pre_poll, and after consume if applicable */
-void grpc_pollset_kick_post_poll(grpc_pollset_kick_state *kick_state, grpc_kick_fd_info *fd_info);
+void grpc_pollset_kick_post_poll(grpc_pollset_kick_state *kick_state,
+                                 grpc_kick_fd_info *fd_info);
 
+/* Actually kick */
 void grpc_pollset_kick_kick(grpc_pollset_kick_state *kick_state);
 
-#endif  /* GRPC_INTERNAL_CORE_IOMGR_POLLSET_KICK_POSIX_H */
+#endif /* GRPC_INTERNAL_CORE_IOMGR_POLLSET_KICK_POSIX_H */