lib/reconnect.h

   1 /*
   2  * Copyright (c) 2009, 2010, 2012 Nicira, Inc.
   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 /* Defaults, all in msecs. */
  44 #define RECONNECT_DEFAULT_MIN_BACKOFF 1000
  45 #define RECONNECT_DEFAULT_MAX_BACKOFF 8000
  46 #define RECONNECT_DEFAULT_PROBE_INTERVAL 5000
  47
  48 int reconnect_get_min_backoff(const struct reconnect *);
  49 int reconnect_get_max_backoff(const struct reconnect *);
  50 int reconnect_get_probe_interval(const struct reconnect *);
  51
  52 void reconnect_set_max_tries(struct reconnect *, unsigned int max_tries);
  53 unsigned int reconnect_get_max_tries(struct reconnect *);
  54 void reconnect_set_backoff_free_tries(struct reconnect *,
  55                                       unsigned int backoff_free_tries);
  56
  57 void reconnect_set_backoff(struct reconnect *,
  58                            int min_backoff, int max_backoff);
  59 void reconnect_set_probe_interval(struct reconnect *, int probe_interval);
  60
  61 bool reconnect_is_passive(const struct reconnect *);
  62 void reconnect_set_passive(struct reconnect *, bool passive,
  63                            long long int now);
  64
  65 bool reconnect_is_enabled(const struct reconnect *);
  66 void reconnect_enable(struct reconnect *, long long int now);
  67 void reconnect_disable(struct reconnect *, long long int now);
  68
  69 void reconnect_force_reconnect(struct reconnect *, long long int now);
  70 void reconnect_skip_backoff(struct reconnect *);
  71
  72 bool reconnect_is_connected(const struct reconnect *);
  73 unsigned int reconnect_get_last_connect_elapsed(const struct reconnect *,
  74                                                 long long int now);
  75 unsigned int reconnect_get_last_disconnect_elapsed(const struct reconnect *,
  76                                                    long long int now);
  77
  78 void reconnect_disconnected(struct reconnect *, long long int now, int error);
  79 void reconnect_connecting(struct reconnect *, long long int now);
  80 void reconnect_listening(struct reconnect *, long long int now);
  81 void reconnect_listen_error(struct reconnect *, long long int now, int error);
  82 void reconnect_connected(struct reconnect *, long long int now);
  83 void reconnect_connect_failed(struct reconnect *, long long int now,
  84                               int error);
  85 void reconnect_activity(struct reconnect *, long long int now);
  86
  87 enum reconnect_action {
  88     RECONNECT_CONNECT = 1,
  89     RECONNECT_DISCONNECT,
  90     RECONNECT_PROBE,
  91 };
  92 enum reconnect_action reconnect_run(struct reconnect *, long long int now);
  93 void reconnect_wait(struct reconnect *, long long int now);
  94 int reconnect_timeout(struct reconnect *, long long int now);
  95
  96 struct reconnect_stats {
  97     /* All times and durations in this structure are in milliseconds. */
  98     long long int creation_time;     /* Time reconnect_create() called. */
  99     long long int last_activity;     /* Last call to reconnect_activity(). */
 100     long long int last_connected;    /* Last call to reconnect_connected(). */
 101     long long int last_disconnected; /* Last call to reconnect_disconnected(). */
 102     int backoff;                     /* Current backoff duration.  */
 103
 104     unsigned int seqno;              /* # of connections + # of disconnections. */
 105
 106     bool is_connected;                     /* Currently connected? */
 107     unsigned int msec_since_connect;       /* Time since last connect. */
 108     unsigned int msec_since_disconnect;    /* Time since last disconnect. */
 109     unsigned int total_connected_duration; /* Sum of all connections. */
 110     unsigned int n_attempted_connections;
 111     unsigned int n_successful_connections;
 112
 113     /* These should only be provided to a human user for debugging purposes.
 114      * The client should not attempt to interpret them. */
 115     const char *state;            /* FSM state. */
 116     unsigned int state_elapsed;   /* Time since FSM state entered. */
 117 };
 118
 119 void reconnect_get_stats(const struct reconnect *, long long int now,
 120                          struct reconnect_stats *);
 121
 122 #endif /* reconnect.h */