Commentary

src/core/iomgr/fd_posix.h

@@ -128,7 +128,9 @@ gpr_uint32 grpc_fd_begin_poll(grpc_fd *fd, grpc_pollset *pollset,
                               grpc_pollset_worker *worker, gpr_uint32 read_mask,
                               gpr_uint32 write_mask, grpc_fd_watcher *rec);
 /* Complete polling previously started with grpc_fd_begin_poll
-   MUST NOT be called with a pollset lock taken */
+   MUST NOT be called with a pollset lock taken
+   if got_read or got_write are 1, also does the notify_on_{read,write} as
+   appropriate. */
 void grpc_fd_end_poll(grpc_exec_ctx *exec_ctx, grpc_fd_watcher *rec,
                       int got_read, int got_write);
 

src/core/iomgr/pollset_posix.h

@@ -112,8 +112,12 @@ void grpc_kick_drain(grpc_pollset *p);
 int grpc_poll_deadline_to_millis_timeout(gpr_timespec deadline,
                                          gpr_timespec now);
 
+/* Allow kick to wakeup the currently polling worker */
 #define GRPC_POLLSET_CAN_KICK_SELF 1
+/* Force the wakee to repoll when awoken */
 #define GRPC_POLLSET_REEVALUATE_POLLING_ON_WAKEUP 2
+/* As per grpc_pollset_kick, with an extended set of flags (defined above)
+   -- mostly for fd_posix's use. */
 void grpc_pollset_kick_ex(grpc_pollset *p, grpc_pollset_worker *specific_worker,
                           gpr_uint32 flags);