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
29struct reactor_t;
30typedef struct reactor_t reactor_t;
31
32struct reactor_object_t;
33typedef struct reactor_object_t reactor_object_t;
34
35// Enumerates the types of events a reactor object is interested
36// in responding to.
37typedef 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.
44typedef 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
51struct 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|.
62reactor_t *reactor_new(void);
63
64// Frees a reactor object created with |reactor_new|. |reactor| may be NULL.
65void 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.
69reactor_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.
73reactor_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.
76reactor_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.
80void 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.
85void 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.
89void reactor_unregister(reactor_t *reactor, reactor_object_t *obj);
90