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 2419084c6242d8ddb366a52eba5084c974280cce0fSharvil Nanavati#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 { 3419084c6242d8ddb366a52eba5084c974280cce0fSharvil Nanavati REACTOR_STATUS_STOP, // |reactor_stop| was called. 3519084c6242d8ddb366a52eba5084c974280cce0fSharvil Nanavati REACTOR_STATUS_ERROR, // there was an error during the operation. 3619084c6242d8ddb366a52eba5084c974280cce0fSharvil Nanavati REACTOR_STATUS_DONE, // the reactor completed its work (for the _run_once* variants). 3719084c6242d8ddb366a52eba5084c974280cce0fSharvil Nanavati} reactor_status_t; 3819084c6242d8ddb366a52eba5084c974280cce0fSharvil Nanavati 3919084c6242d8ddb366a52eba5084c974280cce0fSharvil Nanavati// Creates a new reactor object. Returns NULL on failure. The returned object 4019084c6242d8ddb366a52eba5084c974280cce0fSharvil Nanavati// must be freed by calling |reactor_free|. 4119084c6242d8ddb366a52eba5084c974280cce0fSharvil Nanavatireactor_t *reactor_new(void); 4219084c6242d8ddb366a52eba5084c974280cce0fSharvil Nanavati 4319084c6242d8ddb366a52eba5084c974280cce0fSharvil Nanavati// Frees a reactor object created with |reactor_new|. |reactor| may be NULL. 4419084c6242d8ddb366a52eba5084c974280cce0fSharvil Nanavativoid reactor_free(reactor_t *reactor); 4519084c6242d8ddb366a52eba5084c974280cce0fSharvil Nanavati 4619084c6242d8ddb366a52eba5084c974280cce0fSharvil Nanavati// Starts the reactor. This function blocks the caller until |reactor_stop| is called 4719084c6242d8ddb366a52eba5084c974280cce0fSharvil Nanavati// from another thread or in a callback. |reactor| may not be NULL. 4819084c6242d8ddb366a52eba5084c974280cce0fSharvil Nanavatireactor_status_t reactor_start(reactor_t *reactor); 4919084c6242d8ddb366a52eba5084c974280cce0fSharvil Nanavati 5019084c6242d8ddb366a52eba5084c974280cce0fSharvil Nanavati// Runs one iteration of the reactor. This function blocks until at least one registered object 5119084c6242d8ddb366a52eba5084c974280cce0fSharvil Nanavati// becomes ready. |reactor| may not be NULL. 5219084c6242d8ddb366a52eba5084c974280cce0fSharvil Nanavatireactor_status_t reactor_run_once(reactor_t *reactor); 5319084c6242d8ddb366a52eba5084c974280cce0fSharvil Nanavati 5419084c6242d8ddb366a52eba5084c974280cce0fSharvil Nanavati// Immediately unblocks the reactor. This function is safe to call from any thread. 5519084c6242d8ddb366a52eba5084c974280cce0fSharvil Nanavati// |reactor| may not be NULL. 5619084c6242d8ddb366a52eba5084c974280cce0fSharvil Nanavativoid reactor_stop(reactor_t *reactor); 5719084c6242d8ddb366a52eba5084c974280cce0fSharvil Nanavati 58fbf89085bf308a98b00da77d1538539f6dd58604Sharvil Nanavati// Registers a file descriptor with the reactor. The file descriptor, |fd|, must be valid 59fbf89085bf308a98b00da77d1538539f6dd58604Sharvil Nanavati// when this function is called and its ownership is not transferred to the reactor. The 60fbf89085bf308a98b00da77d1538539f6dd58604Sharvil Nanavati// |context| variable is a user-defined opaque handle that is passed back to the |read_ready| 61fbf89085bf308a98b00da77d1538539f6dd58604Sharvil Nanavati// and |write_ready| functions. It is not copied or even dereferenced by the reactor so it 62fbf89085bf308a98b00da77d1538539f6dd58604Sharvil Nanavati// may contain any value including NULL. The |read_ready| and |write_ready| arguments are 63fbf89085bf308a98b00da77d1538539f6dd58604Sharvil Nanavati// optional and may be NULL. This function returns an opaque object that represents the 64fbf89085bf308a98b00da77d1538539f6dd58604Sharvil Nanavati// file descriptor's registration with the reactor. When the caller is no longer interested 65fbf89085bf308a98b00da77d1538539f6dd58604Sharvil Nanavati// in events on the |fd|, it must free the returned object by calling |reactor_unregister|. 66fbf89085bf308a98b00da77d1538539f6dd58604Sharvil Nanavatireactor_object_t *reactor_register(reactor_t *reactor, 67fbf89085bf308a98b00da77d1538539f6dd58604Sharvil Nanavati int fd, void *context, 68fbf89085bf308a98b00da77d1538539f6dd58604Sharvil Nanavati void (*read_ready)(void *context), 69fbf89085bf308a98b00da77d1538539f6dd58604Sharvil Nanavati void (*write_ready)(void *context)); 70fbf89085bf308a98b00da77d1538539f6dd58604Sharvil Nanavati 71fbf89085bf308a98b00da77d1538539f6dd58604Sharvil Nanavati// Changes the subscription mode for the file descriptor represented by |object|. If the 72fbf89085bf308a98b00da77d1538539f6dd58604Sharvil Nanavati// caller has already registered a file descriptor with a reactor, has a valid |object|, 73fbf89085bf308a98b00da77d1538539f6dd58604Sharvil Nanavati// and decides to change the |read_ready| and/or |write_ready| callback routines, they 74fbf89085bf308a98b00da77d1538539f6dd58604Sharvil Nanavati// can call this routine. Returns true if the subscription was changed, false otherwise. 75fbf89085bf308a98b00da77d1538539f6dd58604Sharvil Nanavati// |object| may not be NULL, |read_ready| and |write_ready| may be NULL. 76fbf89085bf308a98b00da77d1538539f6dd58604Sharvil Nanavatibool reactor_change_registration(reactor_object_t *object, 77fbf89085bf308a98b00da77d1538539f6dd58604Sharvil Nanavati void (*read_ready)(void *context), 78fbf89085bf308a98b00da77d1538539f6dd58604Sharvil Nanavati void (*write_ready)(void *context)); 79fbf89085bf308a98b00da77d1538539f6dd58604Sharvil Nanavati 80fbf89085bf308a98b00da77d1538539f6dd58604Sharvil Nanavati// Unregisters a previously registered file descriptor with its reactor. |obj| may not be NULL. 81fbf89085bf308a98b00da77d1538539f6dd58604Sharvil Nanavati// |obj| is invalid after calling this function so the caller must drop all references to it. 82fbf89085bf308a98b00da77d1538539f6dd58604Sharvil Nanavativoid reactor_unregister(reactor_object_t *obj); 83