GRPC Core  0.11.0.0
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Pages
fd_posix.h
Go to the documentation of this file.
1 /*
2  *
3  * Copyright 2015, Google Inc.
4  * All rights reserved.
5  *
6  * Redistribution and use in source and binary forms, with or without
7  * modification, are permitted provided that the following conditions are
8  * met:
9  *
10  * * Redistributions of source code must retain the above copyright
11  * notice, this list of conditions and the following disclaimer.
12  * * Redistributions in binary form must reproduce the above
13  * copyright notice, this list of conditions and the following disclaimer
14  * in the documentation and/or other materials provided with the
15  * distribution.
16  * * Neither the name of Google Inc. nor the names of its
17  * contributors may be used to endorse or promote products derived from
18  * this software without specific prior written permission.
19  *
20  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
21  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
22  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
23  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
24  * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
25  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
26  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
27  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
28  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
29  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
30  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
31  *
32  */
33 
34 #ifndef GRPC_INTERNAL_CORE_IOMGR_FD_POSIX_H
35 #define GRPC_INTERNAL_CORE_IOMGR_FD_POSIX_H
36 
38 #include "src/core/iomgr/pollset.h"
39 #include <grpc/support/atm.h>
40 #include <grpc/support/sync.h>
41 #include <grpc/support/time.h>
42 
43 typedef struct grpc_fd grpc_fd;
44 
45 typedef struct grpc_fd_watcher {
51 
52 struct grpc_fd {
53  int fd;
54  /* refst format:
55  bit0: 1=active/0=orphaned
56  bit1-n: refcount
57  meaning that mostly we ref by two to avoid altering the orphaned bit,
58  and just unref by 1 when we're ready to flag the object as orphaned */
60 
63  int closed;
64 
65  /* The watcher list.
66 
67  The following watcher related fields are protected by watcher_mu.
68 
69  An fd_watcher is an ephemeral object created when an fd wants to
70  begin polling, and destroyed after the poll.
71 
72  It denotes the fd's interest in whether to read poll or write poll
73  or both or neither on this fd.
74 
75  If a watcher is asked to poll for reads or writes, the read_watcher
76  or write_watcher fields are set respectively. A watcher may be asked
77  to poll for both, in which case both fields will be set.
78 
79  read_watcher and write_watcher may be NULL if no watcher has been
80  asked to poll for reads or writes.
81 
82  If an fd_watcher is not asked to poll for reads or writes, it's added
83  to a linked list of inactive watchers, rooted at inactive_watcher_root.
84  If at a later time there becomes need of a poller to poll, one of
85  the inactive pollers may be kicked out of their poll loops to take
86  that responsibility. */
91 
94 
96 
99 
101 };
102 
103 /* Create a wrapped file descriptor.
104  Requires fd is a non-blocking file descriptor.
105  This takes ownership of closing fd. */
106 grpc_fd *grpc_fd_create(int fd, const char *name);
107 
108 /* Releases fd to be asynchronously destroyed.
109  on_done is called when the underlying file descriptor is definitely close()d.
110  If on_done is NULL, no callback will be made.
111  Requires: *fd initialized; no outstanding notify_on_read or
112  notify_on_write.
113  MUST NOT be called with a pollset lock taken */
115  const char *reason);
116 
117 /* Begin polling on an fd.
118  Registers that the given pollset is interested in this fd - so that if read
119  or writability interest changes, the pollset can be kicked to pick up that
120  new interest.
121  Return value is:
122  (fd_needs_read? read_mask : 0) | (fd_needs_write? write_mask : 0)
123  i.e. a combination of read_mask and write_mask determined by the fd's current
124  interest in said events.
125  Polling strategies that do not need to alter their behavior depending on the
126  fd's current interest (such as epoll) do not need to call this function.
127  MUST NOT be called with a pollset lock taken */
129  gpr_uint32 read_mask, gpr_uint32 write_mask,
130  grpc_fd_watcher *rec);
131 /* Complete polling previously started with grpc_fd_begin_poll
132  MUST NOT be called with a pollset lock taken */
133 void grpc_fd_end_poll(grpc_fd_watcher *rec, int got_read, int got_write);
134 
135 /* Return 1 if this fd is orphaned, 0 otherwise */
137 
138 /* Cause any current callbacks to error out with GRPC_CALLBACK_CANCELLED. */
140 
141 /* Register read interest, causing read_cb to be called once when fd becomes
142  readable, on deadline specified by deadline, or on shutdown triggered by
143  grpc_fd_shutdown.
144  read_cb will be called with read_cb_arg when *fd becomes readable.
145  read_cb is Called with status of GRPC_CALLBACK_SUCCESS if readable,
146  GRPC_CALLBACK_TIMED_OUT if the call timed out,
147  and CANCELLED if the call was cancelled.
148 
149  Requires:This method must not be called before the read_cb for any previous
150  call runs. Edge triggered events are used whenever they are supported by the
151  underlying platform. This means that users must drain fd in read_cb before
152  calling notify_on_read again. Users are also expected to handle spurious
153  events, i.e read_cb is called while nothing can be readable from fd */
155 
156 /* Exactly the same semantics as above, except based on writable events. */
158 
159 /* Notification from the poller to an fd that it has become readable or
160  writable.
161  If allow_synchronous_callback is 1, allow running the fd callback inline
162  in this callstack, otherwise register an asynchronous callback and return */
163 void grpc_fd_become_readable(grpc_fd *fd, int allow_synchronous_callback);
164 void grpc_fd_become_writable(grpc_fd *fd, int allow_synchronous_callback);
165 
166 /* Reference counting for fds */
167 #ifdef GRPC_FD_REF_COUNT_DEBUG
168 void grpc_fd_ref(grpc_fd *fd, const char *reason, const char *file, int line);
169 void grpc_fd_unref(grpc_fd *fd, const char *reason, const char *file, int line);
170 #define GRPC_FD_REF(fd, reason) grpc_fd_ref(fd, reason, __FILE__, __LINE__)
171 #define GRPC_FD_UNREF(fd, reason) grpc_fd_unref(fd, reason, __FILE__, __LINE__)
172 #else
173 void grpc_fd_ref(grpc_fd *fd);
174 void grpc_fd_unref(grpc_fd *fd);
175 #define GRPC_FD_REF(fd, reason) grpc_fd_ref(fd)
176 #define GRPC_FD_UNREF(fd, reason) grpc_fd_unref(fd)
177 #endif
178 
179 void grpc_fd_global_init(void);
180 void grpc_fd_global_shutdown(void);
181 
182 #endif /* GRPC_INTERNAL_CORE_IOMGR_FD_POSIX_H */
gpr_atm shutdown
Definition: fd_posix.h:62
void grpc_fd_shutdown(grpc_fd *fd)
void grpc_fd_become_readable(grpc_fd *fd, int allow_synchronous_callback)
grpc_fd_watcher inactive_watcher_root
Definition: fd_posix.h:88
void grpc_fd_unref(grpc_fd *fd)
struct grpc_fd_watcher * next
Definition: fd_posix.h:46
int fd
Definition: fd_posix.h:53
void grpc_fd_ref(grpc_fd *fd)
grpc_fd * fd
Definition: fd_posix.h:49
grpc_iomgr_closure * on_done_closure
Definition: fd_posix.h:97
void grpc_fd_end_poll(grpc_fd_watcher *rec, int got_read, int got_write)
grpc_pollset * pollset
Definition: fd_posix.h:48
struct grpc_fd_watcher * prev
Definition: fd_posix.h:47
uint32_t gpr_uint32
Definition: port_platform.h:312
void grpc_fd_notify_on_write(grpc_fd *fd, grpc_iomgr_closure *closure)
void grpc_fd_global_init(void)
Definition: pollset_posix.h:55
grpc_iomgr_object iomgr_object
Definition: fd_posix.h:100
struct grpc_fd_watcher grpc_fd_watcher
gpr_atm readst
Definition: fd_posix.h:92
Definition: iomgr_internal.h:40
int closed
Definition: fd_posix.h:63
gpr_uint32 grpc_fd_begin_poll(grpc_fd *fd, grpc_pollset *pollset, gpr_uint32 read_mask, gpr_uint32 write_mask, grpc_fd_watcher *rec)
void grpc_fd_global_shutdown(void)
grpc_fd_watcher * read_watcher
Definition: fd_posix.h:89
gpr_mu watcher_mu
Definition: fd_posix.h:87
Definition: sync_win32.h:39
grpc_fd * grpc_fd_create(int fd, const char *name)
grpc_fd_watcher * write_watcher
Definition: fd_posix.h:90
gpr_atm refst
Definition: fd_posix.h:59
void grpc_fd_notify_on_read(grpc_fd *fd, grpc_iomgr_closure *closure)
A closure over a grpc_iomgr_cb_func.
Definition: iomgr.h:45
void grpc_fd_become_writable(grpc_fd *fd, int allow_synchronous_callback)
int grpc_fd_is_orphaned(grpc_fd *fd)
struct grpc_fd * freelist_next
Definition: fd_posix.h:95
Definition: fd_posix.h:45
grpc_iomgr_closure * shutdown_closures[2]
Definition: fd_posix.h:98
gpr_atm writest
Definition: fd_posix.h:93
gpr_intptr gpr_atm
Definition: atm_gcc_atomic.h:41
gpr_mu set_state_mu
Definition: fd_posix.h:61
void grpc_fd_orphan(grpc_fd *fd, grpc_iomgr_closure *on_done, const char *reason)
Definition: fd_posix.h:52