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 24 #include "osi.h" 25 26 // This module implements the Reactor pattern. 27 // See http://en.wikipedia.org/wiki/Reactor_pattern for details. 28 29 struct reactor_t; 30 typedef struct reactor_t reactor_t; 31 32 struct reactor_object_t; 33 typedef struct reactor_object_t reactor_object_t; 34 35 // Enumerates the types of events a reactor object is interested 36 // in responding to. 37 typedef enum { 38 REACTOR_INTEREST_READ = 1, 39 REACTOR_INTEREST_WRITE = 2, 40 REACTOR_INTEREST_READ_WRITE = 3, 41 } reactor_interest_t; 42 43 // Enumerates the reasons a reactor has stopped. 44 typedef enum { 45 REACTOR_STATUS_STOP, // |reactor_stop| was called. 46 REACTOR_STATUS_TIMEOUT, // a timeout was specified and the reactor timed out. 47 REACTOR_STATUS_ERROR, // there was an error during the operation. 48 REACTOR_STATUS_DONE, // the reactor completed its work (for the _run_once* variants). 49 } reactor_status_t; 50 51 struct reactor_object_t { 52 void *context; // a context that's passed back to the *_ready functions. 53 int fd; // the file descriptor to monitor for events. 54 reactor_interest_t interest; // the event types to monitor the file descriptor for. 55 56 void (*read_ready)(void *context); // function to call when the file descriptor becomes readable. 57 void (*write_ready)(void *context); // function to call when the file descriptor becomes writeable. 58 }; 59 60 // Creates a new reactor object. Returns NULL on failure. The returned object 61 // must be freed by calling |reactor_free|. 62 reactor_t *reactor_new(void); 63 64 // Frees a reactor object created with |reactor_new|. |reactor| may be NULL. 65 void reactor_free(reactor_t *reactor); 66 67 // Starts the reactor. This function blocks the caller until |reactor_stop| is called 68 // from another thread or in a callback. |reactor| may not be NULL. 69 reactor_status_t reactor_start(reactor_t *reactor); 70 71 // Runs one iteration of the reactor. This function blocks until at least one registered object 72 // becomes ready. |reactor| may not be NULL. 73 reactor_status_t reactor_run_once(reactor_t *reactor); 74 75 // Same as |reactor_run_once| with a bounded wait time in case no object becomes ready. 76 reactor_status_t reactor_run_once_timeout(reactor_t *reactor, timeout_t timeout_ms); 77 78 // Immediately unblocks the reactor. This function is safe to call from any thread. 79 // |reactor| may not be NULL. 80 void reactor_stop(reactor_t *reactor); 81 82 // Registers an object with the reactor. |obj| is neither copied nor is its ownership transferred 83 // so the pointer must remain valid until it is unregistered with |reactor_unregister|. Neither 84 // |reactor| nor |obj| may be NULL. 85 void reactor_register(reactor_t *reactor, reactor_object_t *obj); 86 87 // Unregisters a previously registered object with the |reactor|. Neither |reactor| nor |obj| 88 // may be NULL. 89 void reactor_unregister(reactor_t *reactor, reactor_object_t *obj); 90