reconnect: Fix typo in comment.
[sliver-openvswitch.git] / lib / reconnect.h
1 /*
2  * Copyright (c) 2009, 2010 Nicira Networks.
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at:
7  *
8  *     http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16
17 #ifndef RECONNECT_H
18 #define RECONNECT_H 1
19
20 /* This library implements a finite-state machine for connecting and
21  * reconnecting to a network resource with exponential backoff.  It also
22  * provides optional support for detecting a connection on which the peer is no
23  * longer responding.
24  *
25  * The library does not implement anything networking related, only an FSM for
26  * networking code to use.
27  *
28  * Many "reconnect" functions take a "now" argument.  This makes testing easier
29  * since there is no hidden state.  When not testing, just pass the return
30  * value of time_msec() from timeval.h.  (Perhaps this design should be
31  * revisited later.) */
32
33 #include <stdbool.h>
34
35 struct reconnect *reconnect_create(long long int now);
36 void reconnect_destroy(struct reconnect *);
37
38 void reconnect_set_quiet(struct reconnect *, bool quiet);
39
40 const char *reconnect_get_name(const struct reconnect *);
41 void reconnect_set_name(struct reconnect *, const char *name);
42
43 int reconnect_get_min_backoff(const struct reconnect *);
44 int reconnect_get_max_backoff(const struct reconnect *);
45 int reconnect_get_probe_interval(const struct reconnect *);
46
47 void reconnect_set_max_tries(struct reconnect *, unsigned int max_tries);
48 unsigned int reconnect_get_max_tries(struct reconnect *);
49
50 void reconnect_set_backoff(struct reconnect *,
51                            int min_backoff, int max_backoff);
52 void reconnect_set_probe_interval(struct reconnect *, int probe_interval);
53
54 bool reconnect_is_passive(const struct reconnect *);
55 void reconnect_set_passive(struct reconnect *, bool passive,
56                            long long int now);
57
58 bool reconnect_is_enabled(const struct reconnect *);
59 void reconnect_enable(struct reconnect *, long long int now);
60 void reconnect_disable(struct reconnect *, long long int now);
61
62 void reconnect_force_reconnect(struct reconnect *, long long int now);
63
64 bool reconnect_is_connected(const struct reconnect *);
65 unsigned int reconnect_get_connection_duration(const struct reconnect *,
66                                                long long int now);
67
68 void reconnect_disconnected(struct reconnect *, long long int now, int error);
69 void reconnect_connecting(struct reconnect *, long long int now);
70 void reconnect_listening(struct reconnect *, long long int now);
71 void reconnect_listen_error(struct reconnect *, long long int now, int error);
72 void reconnect_connected(struct reconnect *, long long int now);
73 void reconnect_connect_failed(struct reconnect *, long long int now,
74                               int error);
75 void reconnect_received(struct reconnect *, long long int now);
76
77 enum reconnect_action {
78     RECONNECT_CONNECT = 1,
79     RECONNECT_DISCONNECT,
80     RECONNECT_PROBE,
81 };
82 enum reconnect_action reconnect_run(struct reconnect *, long long int now);
83 void reconnect_wait(struct reconnect *, long long int now);
84 int reconnect_timeout(struct reconnect *, long long int now);
85
86 struct reconnect_stats {
87     /* All times and durations in this structure are in milliseconds. */
88     long long int creation_time;  /* Time reconnect_create() called. */
89     long long int last_received; /* Last call to reconnect_received(). */
90     long long int last_connected; /* Last call to reconnect_connected(). */
91     int backoff;                  /* Current backoff duration.  */
92
93     unsigned int seqno;         /* # of connections + # of disconnections. */
94
95     bool is_connected;          /* Currently connected? */
96     unsigned int current_connection_duration; /* Time of current connection. */
97     unsigned int total_connected_duration;    /* Sum of all connections. */
98     unsigned int n_attempted_connections;
99     unsigned int n_successful_connections;
100
101     /* These should only be provided to a human user for debugging purposes.
102      * The client should not attempt to interpret them. */
103     const char *state;            /* FSM state. */
104     unsigned int state_elapsed;   /* Time since FSM state entered. */
105 };
106
107 void reconnect_get_stats(const struct reconnect *, long long int now,
108                          struct reconnect_stats *);
109
110 #endif /* reconnect.h */