David Klempner | 78dc6cd | 2015-01-26 15:02:51 -0800 | [diff] [blame] | 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 | /* |
| 35 | * wakeup_fd abstracts the concept of a file descriptor for the purpose of |
| 36 | * waking up a thread in select()/poll()/epoll_wait()/etc. |
| 37 | |
| 38 | * The poll() family of system calls provide a way for a thread to block until |
| 39 | * there is activity on one (or more) of a set of file descriptors. An |
| 40 | * application may wish to wake up this thread to do non file related work. The |
| 41 | * typical way to do this is to add a pipe to the set of file descriptors, then |
| 42 | * write to the pipe to wake up the thread in poll(). |
| 43 | * |
| 44 | * Linux has a lighter weight eventfd specifically designed for this purpose. |
| 45 | * wakeup_fd abstracts the difference between the two. |
| 46 | * |
| 47 | * Setup: |
| 48 | * 1. Before calling anything, call global_init() at least once. |
| 49 | * 1. Call grpc_wakeup_fd_create() to get a wakeup_fd. |
| 50 | * 2. Add the result of GRPC_WAKEUP_FD_FD to the set of monitored file |
| 51 | * descriptors for the poll() style API you are using. Monitor the file |
| 52 | * descriptor for readability. |
| 53 | * 3. To tear down, call grpc_wakeup_fd_destroy(). This closes the underlying |
| 54 | * file descriptor. |
| 55 | * |
| 56 | * Usage: |
| 57 | * 1. To wake up a polling thread, call grpc_wakeup_fd_wakeup() on a wakeup_fd |
| 58 | * it is monitoring. |
| 59 | * 2. If the polling thread was awakened by a wakeup_fd event, call |
| 60 | * grpc_wakeup_fd_consume_wakeup() on it. |
| 61 | */ |
Nicolas "Pixel" Noble | 1ff52d5 | 2015-03-01 05:24:36 +0100 | [diff] [blame] | 62 | #ifndef GRPC_INTERNAL_CORE_IOMGR_WAKEUP_FD_POSIX_H |
| 63 | #define GRPC_INTERNAL_CORE_IOMGR_WAKEUP_FD_POSIX_H |
David Klempner | 78dc6cd | 2015-01-26 15:02:51 -0800 | [diff] [blame] | 64 | |
Craig Tiller | a82950e | 2015-09-22 12:33:20 -0700 | [diff] [blame^] | 65 | void grpc_wakeup_fd_global_init(void); |
| 66 | void grpc_wakeup_fd_global_destroy(void); |
David Klempner | 78dc6cd | 2015-01-26 15:02:51 -0800 | [diff] [blame] | 67 | |
Craig Tiller | e1a03a6 | 2015-02-02 07:46:55 -0800 | [diff] [blame] | 68 | /* Force using the fallback implementation. This is intended for testing |
| 69 | * purposes only.*/ |
Craig Tiller | a82950e | 2015-09-22 12:33:20 -0700 | [diff] [blame^] | 70 | void grpc_wakeup_fd_global_init_force_fallback(void); |
Craig Tiller | e1a03a6 | 2015-02-02 07:46:55 -0800 | [diff] [blame] | 71 | |
Craig Tiller | 5ddbb9d | 2015-07-29 15:58:11 -0700 | [diff] [blame] | 72 | typedef struct grpc_wakeup_fd grpc_wakeup_fd; |
Craig Tiller | e1a03a6 | 2015-02-02 07:46:55 -0800 | [diff] [blame] | 73 | |
Craig Tiller | a82950e | 2015-09-22 12:33:20 -0700 | [diff] [blame^] | 74 | typedef struct grpc_wakeup_fd_vtable { |
| 75 | void (*init)(grpc_wakeup_fd* fd_info); |
| 76 | void (*consume)(grpc_wakeup_fd* fd_info); |
| 77 | void (*wakeup)(grpc_wakeup_fd* fd_info); |
| 78 | void (*destroy)(grpc_wakeup_fd* fd_info); |
Craig Tiller | e1a03a6 | 2015-02-02 07:46:55 -0800 | [diff] [blame] | 79 | /* Must be called before calling any other functions */ |
Craig Tiller | a82950e | 2015-09-22 12:33:20 -0700 | [diff] [blame^] | 80 | int (*check_availability)(void); |
Craig Tiller | e1a03a6 | 2015-02-02 07:46:55 -0800 | [diff] [blame] | 81 | } grpc_wakeup_fd_vtable; |
| 82 | |
Craig Tiller | a82950e | 2015-09-22 12:33:20 -0700 | [diff] [blame^] | 83 | struct grpc_wakeup_fd { |
Craig Tiller | e1a03a6 | 2015-02-02 07:46:55 -0800 | [diff] [blame] | 84 | int read_fd; |
| 85 | int write_fd; |
| 86 | }; |
| 87 | |
| 88 | #define GRPC_WAKEUP_FD_GET_READ_FD(fd_info) ((fd_info)->read_fd) |
David Klempner | 78dc6cd | 2015-01-26 15:02:51 -0800 | [diff] [blame] | 89 | |
Craig Tiller | a82950e | 2015-09-22 12:33:20 -0700 | [diff] [blame^] | 90 | void grpc_wakeup_fd_init(grpc_wakeup_fd* fd_info); |
| 91 | void grpc_wakeup_fd_consume_wakeup(grpc_wakeup_fd* fd_info); |
| 92 | void grpc_wakeup_fd_wakeup(grpc_wakeup_fd* fd_info); |
| 93 | void grpc_wakeup_fd_destroy(grpc_wakeup_fd* fd_info); |
David Klempner | 78dc6cd | 2015-01-26 15:02:51 -0800 | [diff] [blame] | 94 | |
David Klempner | 78dc6cd | 2015-01-26 15:02:51 -0800 | [diff] [blame] | 95 | /* Defined in some specialized implementation's .c file, or by |
| 96 | * wakeup_fd_nospecial.c if no such implementation exists. */ |
Craig Tiller | e1a03a6 | 2015-02-02 07:46:55 -0800 | [diff] [blame] | 97 | extern const grpc_wakeup_fd_vtable grpc_specialized_wakeup_fd_vtable; |
David Klempner | 78dc6cd | 2015-01-26 15:02:51 -0800 | [diff] [blame] | 98 | |
Craig Tiller | d6c98df | 2015-08-18 09:33:44 -0700 | [diff] [blame] | 99 | #endif /* GRPC_INTERNAL_CORE_IOMGR_WAKEUP_FD_POSIX_H */ |