reactor.h revision b55040cc6448a8847490da807d2b6362aa8cb8d9
119084c6242d8ddb366a52eba5084c974280cce0fSharvil Nanavati/****************************************************************************** 219084c6242d8ddb366a52eba5084c974280cce0fSharvil Nanavati * 319084c6242d8ddb366a52eba5084c974280cce0fSharvil Nanavati * Copyright (C) 2014 Google, Inc. 419084c6242d8ddb366a52eba5084c974280cce0fSharvil Nanavati * 519084c6242d8ddb366a52eba5084c974280cce0fSharvil Nanavati * Licensed under the Apache License, Version 2.0 (the "License"); 619084c6242d8ddb366a52eba5084c974280cce0fSharvil Nanavati * you may not use this file except in compliance with the License. 719084c6242d8ddb366a52eba5084c974280cce0fSharvil Nanavati * You may obtain a copy of the License at: 819084c6242d8ddb366a52eba5084c974280cce0fSharvil Nanavati * 919084c6242d8ddb366a52eba5084c974280cce0fSharvil Nanavati * http://www.apache.org/licenses/LICENSE-2.0 1019084c6242d8ddb366a52eba5084c974280cce0fSharvil Nanavati * 1119084c6242d8ddb366a52eba5084c974280cce0fSharvil Nanavati * Unless required by applicable law or agreed to in writing, software 1219084c6242d8ddb366a52eba5084c974280cce0fSharvil Nanavati * distributed under the License is distributed on an "AS IS" BASIS, 1319084c6242d8ddb366a52eba5084c974280cce0fSharvil Nanavati * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 1419084c6242d8ddb366a52eba5084c974280cce0fSharvil Nanavati * See the License for the specific language governing permissions and 1519084c6242d8ddb366a52eba5084c974280cce0fSharvil Nanavati * limitations under the License. 1619084c6242d8ddb366a52eba5084c974280cce0fSharvil Nanavati * 1719084c6242d8ddb366a52eba5084c974280cce0fSharvil Nanavati ******************************************************************************/ 1819084c6242d8ddb366a52eba5084c974280cce0fSharvil Nanavati 1919084c6242d8ddb366a52eba5084c974280cce0fSharvil Nanavati#pragma once 2019084c6242d8ddb366a52eba5084c974280cce0fSharvil Nanavati 2119084c6242d8ddb366a52eba5084c974280cce0fSharvil Nanavati#include <stdbool.h> 2219084c6242d8ddb366a52eba5084c974280cce0fSharvil Nanavati#include <stdint.h> 2319084c6242d8ddb366a52eba5084c974280cce0fSharvil Nanavati 24c196f214c5ae349ec2022f8d3cbaf56910b3b9f8Pavlin Radoslavov#include "osi/include/osi.h" 2519084c6242d8ddb366a52eba5084c974280cce0fSharvil Nanavati 2619084c6242d8ddb366a52eba5084c974280cce0fSharvil Nanavati// This module implements the Reactor pattern. 2719084c6242d8ddb366a52eba5084c974280cce0fSharvil Nanavati// See http://en.wikipedia.org/wiki/Reactor_pattern for details. 2819084c6242d8ddb366a52eba5084c974280cce0fSharvil Nanavati 29b2a292b5d8df2f359c38b0787bc01181225a9bc9Pavlin Radoslavov#ifdef __cplusplus 30b2a292b5d8df2f359c38b0787bc01181225a9bc9Pavlin Radoslavovextern "C" { 31b2a292b5d8df2f359c38b0787bc01181225a9bc9Pavlin Radoslavov#endif 32b2a292b5d8df2f359c38b0787bc01181225a9bc9Pavlin Radoslavov 3319084c6242d8ddb366a52eba5084c974280cce0fSharvil Nanavatitypedef struct reactor_t reactor_t; 3419084c6242d8ddb366a52eba5084c974280cce0fSharvil Nanavatitypedef struct reactor_object_t reactor_object_t; 3519084c6242d8ddb366a52eba5084c974280cce0fSharvil Nanavati 3619084c6242d8ddb366a52eba5084c974280cce0fSharvil Nanavati// Enumerates the reasons a reactor has stopped. 3719084c6242d8ddb366a52eba5084c974280cce0fSharvil Nanavatitypedef enum { 38b55040cc6448a8847490da807d2b6362aa8cb8d9Myles Watson REACTOR_STATUS_STOP, // |reactor_stop| was called. 39b55040cc6448a8847490da807d2b6362aa8cb8d9Myles Watson REACTOR_STATUS_ERROR, // there was an error during the operation. 40b55040cc6448a8847490da807d2b6362aa8cb8d9Myles Watson REACTOR_STATUS_DONE, // the reactor completed its work (for the _run_once* 41b55040cc6448a8847490da807d2b6362aa8cb8d9Myles Watson // variants). 4219084c6242d8ddb366a52eba5084c974280cce0fSharvil Nanavati} reactor_status_t; 4319084c6242d8ddb366a52eba5084c974280cce0fSharvil Nanavati 4419084c6242d8ddb366a52eba5084c974280cce0fSharvil Nanavati// Creates a new reactor object. Returns NULL on failure. The returned object 4519084c6242d8ddb366a52eba5084c974280cce0fSharvil Nanavati// must be freed by calling |reactor_free|. 46b55040cc6448a8847490da807d2b6362aa8cb8d9Myles Watsonreactor_t* reactor_new(void); 4719084c6242d8ddb366a52eba5084c974280cce0fSharvil Nanavati 4819084c6242d8ddb366a52eba5084c974280cce0fSharvil Nanavati// Frees a reactor object created with |reactor_new|. |reactor| may be NULL. 49b55040cc6448a8847490da807d2b6362aa8cb8d9Myles Watsonvoid reactor_free(reactor_t* reactor); 5019084c6242d8ddb366a52eba5084c974280cce0fSharvil Nanavati 51b55040cc6448a8847490da807d2b6362aa8cb8d9Myles Watson// Starts the reactor. This function blocks the caller until |reactor_stop| is 52b55040cc6448a8847490da807d2b6362aa8cb8d9Myles Watson// called 5319084c6242d8ddb366a52eba5084c974280cce0fSharvil Nanavati// from another thread or in a callback. |reactor| may not be NULL. 54b55040cc6448a8847490da807d2b6362aa8cb8d9Myles Watsonreactor_status_t reactor_start(reactor_t* reactor); 5519084c6242d8ddb366a52eba5084c974280cce0fSharvil Nanavati 56b55040cc6448a8847490da807d2b6362aa8cb8d9Myles Watson// Runs one iteration of the reactor. This function blocks until at least one 57b55040cc6448a8847490da807d2b6362aa8cb8d9Myles Watson// registered object 5819084c6242d8ddb366a52eba5084c974280cce0fSharvil Nanavati// becomes ready. |reactor| may not be NULL. 59b55040cc6448a8847490da807d2b6362aa8cb8d9Myles Watsonreactor_status_t reactor_run_once(reactor_t* reactor); 6019084c6242d8ddb366a52eba5084c974280cce0fSharvil Nanavati 61b55040cc6448a8847490da807d2b6362aa8cb8d9Myles Watson// Immediately unblocks the reactor. This function is safe to call from any 62b55040cc6448a8847490da807d2b6362aa8cb8d9Myles Watson// thread. 6319084c6242d8ddb366a52eba5084c974280cce0fSharvil Nanavati// |reactor| may not be NULL. 64b55040cc6448a8847490da807d2b6362aa8cb8d9Myles Watsonvoid reactor_stop(reactor_t* reactor); 65b55040cc6448a8847490da807d2b6362aa8cb8d9Myles Watson 66b55040cc6448a8847490da807d2b6362aa8cb8d9Myles Watson// Registers a file descriptor with the reactor. The file descriptor, |fd|, must 67b55040cc6448a8847490da807d2b6362aa8cb8d9Myles Watson// be valid 68b55040cc6448a8847490da807d2b6362aa8cb8d9Myles Watson// when this function is called and its ownership is not transferred to the 69b55040cc6448a8847490da807d2b6362aa8cb8d9Myles Watson// reactor. The 70b55040cc6448a8847490da807d2b6362aa8cb8d9Myles Watson// |context| variable is a user-defined opaque handle that is passed back to the 71b55040cc6448a8847490da807d2b6362aa8cb8d9Myles Watson// |read_ready| 72b55040cc6448a8847490da807d2b6362aa8cb8d9Myles Watson// and |write_ready| functions. It is not copied or even dereferenced by the 73b55040cc6448a8847490da807d2b6362aa8cb8d9Myles Watson// reactor so it 74b55040cc6448a8847490da807d2b6362aa8cb8d9Myles Watson// may contain any value including NULL. The |read_ready| and |write_ready| 75b55040cc6448a8847490da807d2b6362aa8cb8d9Myles Watson// arguments are 76b55040cc6448a8847490da807d2b6362aa8cb8d9Myles Watson// optional and may be NULL. This function returns an opaque object that 77b55040cc6448a8847490da807d2b6362aa8cb8d9Myles Watson// represents the 78b55040cc6448a8847490da807d2b6362aa8cb8d9Myles Watson// file descriptor's registration with the reactor. When the caller is no longer 79b55040cc6448a8847490da807d2b6362aa8cb8d9Myles Watson// interested 80b55040cc6448a8847490da807d2b6362aa8cb8d9Myles Watson// in events on the |fd|, it must free the returned object by calling 81b55040cc6448a8847490da807d2b6362aa8cb8d9Myles Watson// |reactor_unregister|. 82b55040cc6448a8847490da807d2b6362aa8cb8d9Myles Watsonreactor_object_t* reactor_register(reactor_t* reactor, int fd, void* context, 83b55040cc6448a8847490da807d2b6362aa8cb8d9Myles Watson void (*read_ready)(void* context), 84b55040cc6448a8847490da807d2b6362aa8cb8d9Myles Watson void (*write_ready)(void* context)); 85b55040cc6448a8847490da807d2b6362aa8cb8d9Myles Watson 86b55040cc6448a8847490da807d2b6362aa8cb8d9Myles Watson// Changes the subscription mode for the file descriptor represented by 87b55040cc6448a8847490da807d2b6362aa8cb8d9Myles Watson// |object|. If the 88b55040cc6448a8847490da807d2b6362aa8cb8d9Myles Watson// caller has already registered a file descriptor with a reactor, has a valid 89b55040cc6448a8847490da807d2b6362aa8cb8d9Myles Watson// |object|, 90b55040cc6448a8847490da807d2b6362aa8cb8d9Myles Watson// and decides to change the |read_ready| and/or |write_ready| callback 91b55040cc6448a8847490da807d2b6362aa8cb8d9Myles Watson// routines, they 92b55040cc6448a8847490da807d2b6362aa8cb8d9Myles Watson// can call this routine. Returns true if the subscription was changed, false 93b55040cc6448a8847490da807d2b6362aa8cb8d9Myles Watson// otherwise. 94fbf89085bf308a98b00da77d1538539f6dd58604Sharvil Nanavati// |object| may not be NULL, |read_ready| and |write_ready| may be NULL. 95b55040cc6448a8847490da807d2b6362aa8cb8d9Myles Watsonbool reactor_change_registration(reactor_object_t* object, 96b55040cc6448a8847490da807d2b6362aa8cb8d9Myles Watson void (*read_ready)(void* context), 97b55040cc6448a8847490da807d2b6362aa8cb8d9Myles Watson void (*write_ready)(void* context)); 98b55040cc6448a8847490da807d2b6362aa8cb8d9Myles Watson 99b55040cc6448a8847490da807d2b6362aa8cb8d9Myles Watson// Unregisters a previously registered file descriptor with its reactor. |obj| 100b55040cc6448a8847490da807d2b6362aa8cb8d9Myles Watson// may not be NULL. 101b55040cc6448a8847490da807d2b6362aa8cb8d9Myles Watson// |obj| is invalid after calling this function so the caller must drop all 102b55040cc6448a8847490da807d2b6362aa8cb8d9Myles Watson// references to it. 103b55040cc6448a8847490da807d2b6362aa8cb8d9Myles Watsonvoid reactor_unregister(reactor_object_t* obj); 104b2a292b5d8df2f359c38b0787bc01181225a9bc9Pavlin Radoslavov 105b2a292b5d8df2f359c38b0787bc01181225a9bc9Pavlin Radoslavov#ifdef __cplusplus 106b2a292b5d8df2f359c38b0787bc01181225a9bc9Pavlin Radoslavov} 107b2a292b5d8df2f359c38b0787bc01181225a9bc9Pavlin Radoslavov#endif 108