1 /****************************************************************************** 2 * 3 * Copyright 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/include/osi.h" 25 26 // This module implements the Reactor pattern. 27 // See http://en.wikipedia.org/wiki/Reactor_pattern for details. 28 29 typedef struct reactor_t reactor_t; 30 typedef struct reactor_object_t reactor_object_t; 31 32 // Enumerates the reasons a reactor has stopped. 33 typedef enum { 34 REACTOR_STATUS_STOP, // |reactor_stop| was called. 35 REACTOR_STATUS_ERROR, // there was an error during the operation. 36 REACTOR_STATUS_DONE, // the reactor completed its work (for the _run_once* 37 // variants). 38 } reactor_status_t; 39 40 // Creates a new reactor object. Returns NULL on failure. The returned object 41 // must be freed by calling |reactor_free|. 42 reactor_t* reactor_new(void); 43 44 // Frees a reactor object created with |reactor_new|. |reactor| may be NULL. 45 void reactor_free(reactor_t* reactor); 46 47 // Starts the reactor. This function blocks the caller until |reactor_stop| is 48 // called from another thread or in a callback. |reactor| may not be NULL. 49 reactor_status_t reactor_start(reactor_t* reactor); 50 51 // Runs one iteration of the reactor. This function blocks until at least one 52 // registered object becomes ready. |reactor| may not be NULL. 53 reactor_status_t reactor_run_once(reactor_t* reactor); 54 55 // Immediately unblocks the reactor. This function is safe to call from any 56 // thread. 57 // |reactor| may not be NULL. 58 void reactor_stop(reactor_t* reactor); 59 60 // Registers a file descriptor with the reactor. The file descriptor, |fd|, must 61 // be valid when this function is called and its ownership is not transferred 62 // to the reactor. The |context| variable is a user-defined opaque handle that 63 // is passed back to the |read_ready| and |write_ready| functions. It is not 64 // copied or even dereferenced by the reactor so it may contain any value 65 // including NULL. The |read_ready| and |write_ready| arguments are optional and 66 // may be NULL. This function returns an opaque object that represents the file 67 // descriptor's registration with the reactor. When the caller is no longer 68 // interested in events on the |fd|, it must free the returned object by calling 69 // |reactor_unregister|. 70 reactor_object_t* reactor_register(reactor_t* reactor, int fd, void* context, 71 void (*read_ready)(void* context), 72 void (*write_ready)(void* context)); 73 74 // Changes the subscription mode for the file descriptor represented by 75 // |object|. If the caller has already registered a file descriptor with a 76 // reactor, has a valid |object|, and decides to change the |read_ready| and/or 77 // |write_ready| callback routines, they can call this routine. Returns true if 78 // the subscription was changed, false otherwise. 79 // |object| may not be NULL, |read_ready| and |write_ready| may be NULL. 80 bool reactor_change_registration(reactor_object_t* object, 81 void (*read_ready)(void* context), 82 void (*write_ready)(void* context)); 83 84 // Unregisters a previously registered file descriptor with its reactor. |obj| 85 // may not be NULL. |obj| is invalid after calling this function so the caller 86 // must drop all references to it. 87 void reactor_unregister(reactor_object_t* obj); 88