Sharvil Nanavati | 19084c6 | 2014-06-23 16:30:46 -0700 | [diff] [blame] | 1 | /****************************************************************************** |
| 2 | * |
| 3 | * Copyright (C) 2014 Google, Inc. |
| 4 | * |
| 5 | * Licensed under the Apache License, Version 2.0 (the "License"); |
| 6 | * you may not use this file except in compliance with the License. |
| 7 | * You may obtain a copy of the License at: |
| 8 | * |
| 9 | * http://www.apache.org/licenses/LICENSE-2.0 |
| 10 | * |
| 11 | * Unless required by applicable law or agreed to in writing, software |
| 12 | * distributed under the License is distributed on an "AS IS" BASIS, |
| 13 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| 14 | * See the License for the specific language governing permissions and |
| 15 | * limitations under the License. |
| 16 | * |
| 17 | ******************************************************************************/ |
| 18 | |
| 19 | #pragma once |
| 20 | |
| 21 | #include <stdbool.h> |
| 22 | #include <stdint.h> |
| 23 | |
Pavlin Radoslavov | c196f21 | 2015-09-23 20:39:53 -0700 | [diff] [blame] | 24 | #include "osi/include/osi.h" |
Sharvil Nanavati | 19084c6 | 2014-06-23 16:30:46 -0700 | [diff] [blame] | 25 | |
| 26 | // This module implements the Reactor pattern. |
| 27 | // See http://en.wikipedia.org/wiki/Reactor_pattern for details. |
| 28 | |
Pavlin Radoslavov | b2a292b | 2016-10-14 19:34:48 -0700 | [diff] [blame] | 29 | #ifdef __cplusplus |
| 30 | extern "C" { |
| 31 | #endif |
| 32 | |
Sharvil Nanavati | 19084c6 | 2014-06-23 16:30:46 -0700 | [diff] [blame] | 33 | typedef struct reactor_t reactor_t; |
Sharvil Nanavati | 19084c6 | 2014-06-23 16:30:46 -0700 | [diff] [blame] | 34 | typedef struct reactor_object_t reactor_object_t; |
| 35 | |
Sharvil Nanavati | 19084c6 | 2014-06-23 16:30:46 -0700 | [diff] [blame] | 36 | // Enumerates the reasons a reactor has stopped. |
| 37 | typedef enum { |
Myles Watson | b55040c | 2016-10-19 13:15:34 -0700 | [diff] [blame^] | 38 | REACTOR_STATUS_STOP, // |reactor_stop| was called. |
| 39 | REACTOR_STATUS_ERROR, // there was an error during the operation. |
| 40 | REACTOR_STATUS_DONE, // the reactor completed its work (for the _run_once* |
| 41 | // variants). |
Sharvil Nanavati | 19084c6 | 2014-06-23 16:30:46 -0700 | [diff] [blame] | 42 | } reactor_status_t; |
| 43 | |
Sharvil Nanavati | 19084c6 | 2014-06-23 16:30:46 -0700 | [diff] [blame] | 44 | // Creates a new reactor object. Returns NULL on failure. The returned object |
| 45 | // must be freed by calling |reactor_free|. |
Myles Watson | b55040c | 2016-10-19 13:15:34 -0700 | [diff] [blame^] | 46 | reactor_t* reactor_new(void); |
Sharvil Nanavati | 19084c6 | 2014-06-23 16:30:46 -0700 | [diff] [blame] | 47 | |
| 48 | // Frees a reactor object created with |reactor_new|. |reactor| may be NULL. |
Myles Watson | b55040c | 2016-10-19 13:15:34 -0700 | [diff] [blame^] | 49 | void reactor_free(reactor_t* reactor); |
Sharvil Nanavati | 19084c6 | 2014-06-23 16:30:46 -0700 | [diff] [blame] | 50 | |
Myles Watson | b55040c | 2016-10-19 13:15:34 -0700 | [diff] [blame^] | 51 | // Starts the reactor. This function blocks the caller until |reactor_stop| is |
| 52 | // called |
Sharvil Nanavati | 19084c6 | 2014-06-23 16:30:46 -0700 | [diff] [blame] | 53 | // from another thread or in a callback. |reactor| may not be NULL. |
Myles Watson | b55040c | 2016-10-19 13:15:34 -0700 | [diff] [blame^] | 54 | reactor_status_t reactor_start(reactor_t* reactor); |
Sharvil Nanavati | 19084c6 | 2014-06-23 16:30:46 -0700 | [diff] [blame] | 55 | |
Myles Watson | b55040c | 2016-10-19 13:15:34 -0700 | [diff] [blame^] | 56 | // Runs one iteration of the reactor. This function blocks until at least one |
| 57 | // registered object |
Sharvil Nanavati | 19084c6 | 2014-06-23 16:30:46 -0700 | [diff] [blame] | 58 | // becomes ready. |reactor| may not be NULL. |
Myles Watson | b55040c | 2016-10-19 13:15:34 -0700 | [diff] [blame^] | 59 | reactor_status_t reactor_run_once(reactor_t* reactor); |
Sharvil Nanavati | 19084c6 | 2014-06-23 16:30:46 -0700 | [diff] [blame] | 60 | |
Myles Watson | b55040c | 2016-10-19 13:15:34 -0700 | [diff] [blame^] | 61 | // Immediately unblocks the reactor. This function is safe to call from any |
| 62 | // thread. |
Sharvil Nanavati | 19084c6 | 2014-06-23 16:30:46 -0700 | [diff] [blame] | 63 | // |reactor| may not be NULL. |
Myles Watson | b55040c | 2016-10-19 13:15:34 -0700 | [diff] [blame^] | 64 | void reactor_stop(reactor_t* reactor); |
Sharvil Nanavati | 19084c6 | 2014-06-23 16:30:46 -0700 | [diff] [blame] | 65 | |
Myles Watson | b55040c | 2016-10-19 13:15:34 -0700 | [diff] [blame^] | 66 | // Registers a file descriptor with the reactor. The file descriptor, |fd|, must |
| 67 | // be valid |
| 68 | // when this function is called and its ownership is not transferred to the |
| 69 | // reactor. The |
| 70 | // |context| variable is a user-defined opaque handle that is passed back to the |
| 71 | // |read_ready| |
| 72 | // and |write_ready| functions. It is not copied or even dereferenced by the |
| 73 | // reactor so it |
| 74 | // may contain any value including NULL. The |read_ready| and |write_ready| |
| 75 | // arguments are |
| 76 | // optional and may be NULL. This function returns an opaque object that |
| 77 | // represents the |
| 78 | // file descriptor's registration with the reactor. When the caller is no longer |
| 79 | // interested |
| 80 | // in events on the |fd|, it must free the returned object by calling |
| 81 | // |reactor_unregister|. |
| 82 | reactor_object_t* reactor_register(reactor_t* reactor, int fd, void* context, |
| 83 | void (*read_ready)(void* context), |
| 84 | void (*write_ready)(void* context)); |
Sharvil Nanavati | 19084c6 | 2014-06-23 16:30:46 -0700 | [diff] [blame] | 85 | |
Myles Watson | b55040c | 2016-10-19 13:15:34 -0700 | [diff] [blame^] | 86 | // Changes the subscription mode for the file descriptor represented by |
| 87 | // |object|. If the |
| 88 | // caller has already registered a file descriptor with a reactor, has a valid |
| 89 | // |object|, |
| 90 | // and decides to change the |read_ready| and/or |write_ready| callback |
| 91 | // routines, they |
| 92 | // can call this routine. Returns true if the subscription was changed, false |
| 93 | // otherwise. |
Sharvil Nanavati | fbf8908 | 2014-08-13 00:40:49 -0700 | [diff] [blame] | 94 | // |object| may not be NULL, |read_ready| and |write_ready| may be NULL. |
Myles Watson | b55040c | 2016-10-19 13:15:34 -0700 | [diff] [blame^] | 95 | bool reactor_change_registration(reactor_object_t* object, |
| 96 | void (*read_ready)(void* context), |
| 97 | void (*write_ready)(void* context)); |
Sharvil Nanavati | fbf8908 | 2014-08-13 00:40:49 -0700 | [diff] [blame] | 98 | |
Myles Watson | b55040c | 2016-10-19 13:15:34 -0700 | [diff] [blame^] | 99 | // Unregisters a previously registered file descriptor with its reactor. |obj| |
| 100 | // may not be NULL. |
| 101 | // |obj| is invalid after calling this function so the caller must drop all |
| 102 | // references to it. |
| 103 | void reactor_unregister(reactor_object_t* obj); |
Pavlin Radoslavov | b2a292b | 2016-10-14 19:34:48 -0700 | [diff] [blame] | 104 | |
| 105 | #ifdef __cplusplus |
| 106 | } |
| 107 | #endif |