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 2919084c6242d8ddb366a52eba5084c974280cce0fSharvil Nanavatitypedef struct reactor_t reactor_t; 3019084c6242d8ddb366a52eba5084c974280cce0fSharvil Nanavatitypedef struct reactor_object_t reactor_object_t; 3119084c6242d8ddb366a52eba5084c974280cce0fSharvil Nanavati 3219084c6242d8ddb366a52eba5084c974280cce0fSharvil Nanavati// Enumerates the reasons a reactor has stopped. 3319084c6242d8ddb366a52eba5084c974280cce0fSharvil Nanavatitypedef enum { 34b55040cc6448a8847490da807d2b6362aa8cb8d9Myles Watson REACTOR_STATUS_STOP, // |reactor_stop| was called. 35b55040cc6448a8847490da807d2b6362aa8cb8d9Myles Watson REACTOR_STATUS_ERROR, // there was an error during the operation. 36b55040cc6448a8847490da807d2b6362aa8cb8d9Myles Watson REACTOR_STATUS_DONE, // the reactor completed its work (for the _run_once* 37b55040cc6448a8847490da807d2b6362aa8cb8d9Myles Watson // variants). 3819084c6242d8ddb366a52eba5084c974280cce0fSharvil Nanavati} reactor_status_t; 3919084c6242d8ddb366a52eba5084c974280cce0fSharvil Nanavati 4019084c6242d8ddb366a52eba5084c974280cce0fSharvil Nanavati// Creates a new reactor object. Returns NULL on failure. The returned object 4119084c6242d8ddb366a52eba5084c974280cce0fSharvil Nanavati// must be freed by calling |reactor_free|. 42b55040cc6448a8847490da807d2b6362aa8cb8d9Myles Watsonreactor_t* reactor_new(void); 4319084c6242d8ddb366a52eba5084c974280cce0fSharvil Nanavati 4419084c6242d8ddb366a52eba5084c974280cce0fSharvil Nanavati// Frees a reactor object created with |reactor_new|. |reactor| may be NULL. 45b55040cc6448a8847490da807d2b6362aa8cb8d9Myles Watsonvoid reactor_free(reactor_t* reactor); 4619084c6242d8ddb366a52eba5084c974280cce0fSharvil Nanavati 47b55040cc6448a8847490da807d2b6362aa8cb8d9Myles Watson// Starts the reactor. This function blocks the caller until |reactor_stop| is 489ca07091a1f07ea201cee0504dab6a1d7073d429Myles Watson// called from another thread or in a callback. |reactor| may not be NULL. 49b55040cc6448a8847490da807d2b6362aa8cb8d9Myles Watsonreactor_status_t reactor_start(reactor_t* reactor); 5019084c6242d8ddb366a52eba5084c974280cce0fSharvil Nanavati 51b55040cc6448a8847490da807d2b6362aa8cb8d9Myles Watson// Runs one iteration of the reactor. This function blocks until at least one 529ca07091a1f07ea201cee0504dab6a1d7073d429Myles Watson// registered object becomes ready. |reactor| may not be NULL. 53b55040cc6448a8847490da807d2b6362aa8cb8d9Myles Watsonreactor_status_t reactor_run_once(reactor_t* reactor); 5419084c6242d8ddb366a52eba5084c974280cce0fSharvil Nanavati 55b55040cc6448a8847490da807d2b6362aa8cb8d9Myles Watson// Immediately unblocks the reactor. This function is safe to call from any 56b55040cc6448a8847490da807d2b6362aa8cb8d9Myles Watson// thread. 5719084c6242d8ddb366a52eba5084c974280cce0fSharvil Nanavati// |reactor| may not be NULL. 58b55040cc6448a8847490da807d2b6362aa8cb8d9Myles Watsonvoid reactor_stop(reactor_t* reactor); 59b55040cc6448a8847490da807d2b6362aa8cb8d9Myles Watson 60b55040cc6448a8847490da807d2b6362aa8cb8d9Myles Watson// Registers a file descriptor with the reactor. The file descriptor, |fd|, must 619ca07091a1f07ea201cee0504dab6a1d7073d429Myles Watson// be valid when this function is called and its ownership is not transferred 629ca07091a1f07ea201cee0504dab6a1d7073d429Myles Watson// to the reactor. The |context| variable is a user-defined opaque handle that 639ca07091a1f07ea201cee0504dab6a1d7073d429Myles Watson// is passed back to the |read_ready| and |write_ready| functions. It is not 649ca07091a1f07ea201cee0504dab6a1d7073d429Myles Watson// copied or even dereferenced by the reactor so it may contain any value 659ca07091a1f07ea201cee0504dab6a1d7073d429Myles Watson// including NULL. The |read_ready| and |write_ready| arguments are optional and 669ca07091a1f07ea201cee0504dab6a1d7073d429Myles Watson// may be NULL. This function returns an opaque object that represents the file 679ca07091a1f07ea201cee0504dab6a1d7073d429Myles Watson// descriptor's registration with the reactor. When the caller is no longer 689ca07091a1f07ea201cee0504dab6a1d7073d429Myles Watson// interested in events on the |fd|, it must free the returned object by calling 69b55040cc6448a8847490da807d2b6362aa8cb8d9Myles Watson// |reactor_unregister|. 70b55040cc6448a8847490da807d2b6362aa8cb8d9Myles Watsonreactor_object_t* reactor_register(reactor_t* reactor, int fd, void* context, 71b55040cc6448a8847490da807d2b6362aa8cb8d9Myles Watson void (*read_ready)(void* context), 72b55040cc6448a8847490da807d2b6362aa8cb8d9Myles Watson void (*write_ready)(void* context)); 73b55040cc6448a8847490da807d2b6362aa8cb8d9Myles Watson 74b55040cc6448a8847490da807d2b6362aa8cb8d9Myles Watson// Changes the subscription mode for the file descriptor represented by 759ca07091a1f07ea201cee0504dab6a1d7073d429Myles Watson// |object|. If the caller has already registered a file descriptor with a 769ca07091a1f07ea201cee0504dab6a1d7073d429Myles Watson// reactor, has a valid |object|, and decides to change the |read_ready| and/or 779ca07091a1f07ea201cee0504dab6a1d7073d429Myles Watson// |write_ready| callback routines, they can call this routine. Returns true if 789ca07091a1f07ea201cee0504dab6a1d7073d429Myles Watson// the subscription was changed, false otherwise. 79fbf89085bf308a98b00da77d1538539f6dd58604Sharvil Nanavati// |object| may not be NULL, |read_ready| and |write_ready| may be NULL. 80b55040cc6448a8847490da807d2b6362aa8cb8d9Myles Watsonbool reactor_change_registration(reactor_object_t* object, 81b55040cc6448a8847490da807d2b6362aa8cb8d9Myles Watson void (*read_ready)(void* context), 82b55040cc6448a8847490da807d2b6362aa8cb8d9Myles Watson void (*write_ready)(void* context)); 83b55040cc6448a8847490da807d2b6362aa8cb8d9Myles Watson 84b55040cc6448a8847490da807d2b6362aa8cb8d9Myles Watson// Unregisters a previously registered file descriptor with its reactor. |obj| 859ca07091a1f07ea201cee0504dab6a1d7073d429Myles Watson// may not be NULL. |obj| is invalid after calling this function so the caller 869ca07091a1f07ea201cee0504dab6a1d7073d429Myles Watson// must drop all references to it. 87b55040cc6448a8847490da807d2b6362aa8cb8d9Myles Watsonvoid reactor_unregister(reactor_object_t* obj); 88