GRPC Core  0.10.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. */
114  const char *reason);
115 
116 /* Begin polling on an fd.
117  Registers that the given pollset is interested in this fd - so that if read
118  or writability interest changes, the pollset can be kicked to pick up that
119  new interest.
120  Return value is:
121  (fd_needs_read? read_mask : 0) | (fd_needs_write? write_mask : 0)
122  i.e. a combination of read_mask and write_mask determined by the fd's current
123  interest in said events.
124  Polling strategies that do not need to alter their behavior depending on the
125  fd's current interest (such as epoll) do not need to call this function. */
127  gpr_uint32 read_mask, gpr_uint32 write_mask,
128  grpc_fd_watcher *rec);
129 /* Complete polling previously started with grpc_fd_begin_poll */
130 void grpc_fd_end_poll(grpc_fd_watcher *rec, int got_read, int got_write);
131 
132 /* Return 1 if this fd is orphaned, 0 otherwise */
134 
135 /* Cause any current callbacks to error out with GRPC_CALLBACK_CANCELLED. */
137 
138 /* Register read interest, causing read_cb to be called once when fd becomes
139  readable, on deadline specified by deadline, or on shutdown triggered by
140  grpc_fd_shutdown.
141  read_cb will be called with read_cb_arg when *fd becomes readable.
142  read_cb is Called with status of GRPC_CALLBACK_SUCCESS if readable,
143  GRPC_CALLBACK_TIMED_OUT if the call timed out,
144  and CANCELLED if the call was cancelled.
145 
146  Requires:This method must not be called before the read_cb for any previous
147  call runs. Edge triggered events are used whenever they are supported by the
148  underlying platform. This means that users must drain fd in read_cb before
149  calling notify_on_read again. Users are also expected to handle spurious
150  events, i.e read_cb is called while nothing can be readable from fd */
152 
153 /* Exactly the same semantics as above, except based on writable events. */
155 
156 /* Notification from the poller to an fd that it has become readable or
157  writable.
158  If allow_synchronous_callback is 1, allow running the fd callback inline
159  in this callstack, otherwise register an asynchronous callback and return */
160 void grpc_fd_become_readable(grpc_fd *fd, int allow_synchronous_callback);
161 void grpc_fd_become_writable(grpc_fd *fd, int allow_synchronous_callback);
162 
163 /* Reference counting for fds */
164 #ifdef GRPC_FD_REF_COUNT_DEBUG
165 void grpc_fd_ref(grpc_fd *fd, const char *reason, const char *file, int line);
166 void grpc_fd_unref(grpc_fd *fd, const char *reason, const char *file, int line);
167 #define GRPC_FD_REF(fd, reason) grpc_fd_ref(fd, reason, __FILE__, __LINE__)
168 #define GRPC_FD_UNREF(fd, reason) grpc_fd_unref(fd, reason, __FILE__, __LINE__)
169 #else
170 void grpc_fd_ref(grpc_fd *fd);
171 void grpc_fd_unref(grpc_fd *fd);
172 #define GRPC_FD_REF(fd, reason) grpc_fd_ref(fd)
173 #define GRPC_FD_UNREF(fd, reason) grpc_fd_unref(fd)
174 #endif
175 
176 void grpc_fd_global_init(void);
177 void grpc_fd_global_shutdown(void);
178 
179 #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:309
void grpc_fd_notify_on_write(grpc_fd *fd, grpc_iomgr_closure *closure)
void grpc_fd_global_init(void)
Definition: pollset_posix.h:48
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