connection_table.h

Go to the documentation of this file.

#ifndef CONNECTION_TABLE_CLASS
#define CONNECTION_TABLE_CLASS

/*****************************************************************************\
*                                                                             *
*  Name   : connection_table                                                  *
*  Author : Chris Koeritz                                                     *
*                                                                             *
*  Purpose:                                                                   *
*                                                                             *
*    Manages a list of virtual connections.                                   *
*                                                                             *
*******************************************************************************
* Copyright (c) 1992-$now By Author.  This program is free software; you can  *
* redistribute it and/or modify it under the terms of the GNU General Public  *
* License as published by the Free Software Foundation; either version 2 of   *
* the License or (at your option) any later version.  This is online at:      *
*     http://www.fsf.org/copyleft/gpl.html                                    *
* Please send any updates to: fred@gruntose.com                               *
\*****************************************************************************/

#include "connections_dll.h"

// forward.
class connection;
class conntab_hash;

class CONNECTIONS_CLASS_STYLE connection_table
{
public:
  connection_table(int heartbeats_count, int freshness_period,
          int ghost_period);
    // creates a table that manages a set of connections.  "heartbeat_count" is
    // the number of times a refresh of the connection is attempted (without
    // getting a response) before marking the connection dead.  the
    // "freshness_period" is how long (ms) a connection goes between heartbeat
    // checks.  "ghost_period" is how long (ms) the connection lingers in the
    // table before really getting whacked.  the "diagnostic" is used as the
    // target for problem complaints.

  virtual ~connection_table();

  IMPLEMENT_CLASS_NAME("connection_table");

  enum sides { LOCAL_LINK, REMOTE_LINK, LOCAL_REAL };
    // a simple enum where local represents something on this machine and
    // remote means something on another machine.

  bool live(const connection_id &conn_id);
    // returns true if the "conn_id" is a live connection.

  bool connected(const connection_id &conn_id);
    // returns true if the connection with "conn_id" is currently active.

  connection_id add(const connection &to_add);
    // places a new connection in the connection table and returns the
    // connection id stored in "to_add" on success.  this id must be allocated
    // prior to calling add().  it is a nasty error if the host and id already
    // exist; an invalid connection_id is returned in that case.

  connection_id update(const connection &to_update);
    // locates a connection by the connection id in "to_update" and
    // copies all information from "to_update" into it.

  bool find(const connection_id &conn_id, connection &to_fill);
    // finds the connection for the "conn_id".  the return value
    // is true if the search succeeded.

  bool zap(const connection_id &conn_id);
    // removes a connection "conn_id" from the list.  true is returned if the
    // connection id was deleted.  this does not actually completely trash the
    // connection; it merely marks it as dead.  the connection will be
    // destroyed at a later time but is effectively dead.

  bool transport_connected(const transport_id &tran_id);
    // returns true if the linked or real transport that has "tran_id" has any
    // active connections.  if the transport is real, then the result is
    // true if any linked transports using that real transport are connected.

  int count_users(const transport_id &real_id,
          const transport_id &ignored_link_id, int low_level_id, int level);
    // returns the number of connections using the "low_level_id" at the
    // specified "level" for the real transport with "real_id" and ignores
    // the "ignored_link_id" in this count.

  connection_id find_linked(sides side, const transport_id &tran_id);
    // returns the connection id in use by the linked transport with an
    // id of "tran_id".  since a linked transport can only have one connection,
    // the id is a unique key for the connection.  the "side" tells whether to
    // match the local or remote transport id.

  connection_id find_low_level(network_address::address_type type,
          int low_level_id, int level = 0);
    // looks for a connection of the "type" specified that has the
    // "low_level_id".  this is needed for translating from a low level
    // protocol id to one of our transports.  the connection id for that
    // low level id is returned.  the "level" is used to index into the
    // low level id array.  currently zero and one are supported as indices.

  connection_id find_destination(const transport_id &real_id,
          const network_address &destination);
    // finds the connection id for a linked transport that is hooked up to
    // the "real_id" and has the "destination".

  transport_id socket_to_real_transport(network_address::address_type type,
          int socket, transport_id &linked_id);
    // converts a socket number to the real transport that's managing it.
    // if the socket is also associated with a link, then the id is returned
    // in "linked_id".

  connection_id find_state(const transport_id &real_id,
          connection::states to_find, int low_level);
    // locates the first connection that uses the "real_id" and is in the
    // state "to_find".  if the "low_level" is a normal number, only the
    // connection with the state "to_find" and the primary low-level id of
    // "low_level" will match.  if "low_level" is zero, then only connections
    // that have no primary low-level id yet will match.  if "low_level" is
    // negative, then any connection in the right state will match.

  int get_low_level_id(const transport_id &real_id, int level);
    // finds a live and connected connection that has the "real_id" and
    // returns the low-level unique_id at the "level" specified.

  void clear_dead();
    // removes all connections that are marked as dead and that have had their
    // time stamp expire.

  bool reset_time(const connection_id &conn_id);
  bool kabump(const connection_id &conn_id) { return reset_time(conn_id); }
    // resets the time_stamp associated with the "conn_id" indicating that
    // something has occurred recently to make us think it's still a live
    // connection.

  bool record_request(const connection_id &conn_id);
  bool made_request(const connection_id &conn_id)
          { return record_request(conn_id); }
    // increments the missed heartbeats parameter on the occasion of a
    // heartbeat request.  the number missed can be reset with "reset_time".

  heartbeat liveness(const connection_id &conn_id);
  bool set_liveness(const connection_id &conn_id,
          const heartbeat &new_liveness);
    // allow the heartbeat for the connection to be mangled.

  void show_connections(istring &output, int indentation = 0,
          bool alive_only = false);
    // prints a list of the active connections to the debugging window at
    // "handle".  if "alive_only" is true, then only the live connections are
    // shown.

  int connections() const;
    // returns the current number of connections in the table.

  connection::states get_conn_state(const transport_id &tran_id);
    // returns the current state of the connection for the transport
    // with "tran_id".

  bool set_conn_state(const transport_id &tran_id, connection::states state);
    // sets the connection "state" for the transport with "tran_id".  true is
    // returned if the "tran_id" was found successfully and modified.

  int set_conn_states(const transport_id &real_id, connection::states state);
    // sets all transports linked to the "real_id" to the "state" specified.
    // the number of connections processed is returned.

  bool owns_connection(const connection_id &conn_id,
          const transport_id &link_id);
    // returns true if the connection "conn_id" is owned by the linked
    // transport with the specified "link_id".

  int connections_on_primary(const transport_id &real_id,
          const transport_id &ignored_link_id, int primary_id);
    // looks up the number of connections on the real_transport_id "real_id"
    // that use the "primary_id" as their primary low-level id.  this ignores
    // any reference to the "ignored_link_id", since that's the object that's
    // going away.

  void complain_missing_connection(const connection_id &conn_id,
          const istring &where) const;
    // used to decry the non-finding of a connection.  "conn_id" is the
    // connection that could not be found and "where" is the location inside
    // the program where it was supposed to be found.

  int_set find_related_conns(int low_level_primary, int real_transport);
    // returns the set of connection ids that have "low_level_primary" as their
    // PRIMARY low level id and "real_transport" as their real transport's id.

  int_set find_live_reals();
    // returns a list of all the valid real transport ids, based on the set
    // of connections that are alive.

  connection_id find_dupe(int real_transport, int low_level_primary,
          const network_address &sender, int other_side_transport);
    // returns the first connection id found that matches all of these
    // parameters.  this is vital to check when allowing a connection to be
    // made since a prolonged connection attempt could build up some redundant
    // connection intro packets.

private:
  conntab_hash *_connection_list;  // repository for connection info.
  mutex *_connlock;  // protects access to the list of connections.

  // constructor parameters: see docs above.
  int _heartbeats_until_expiration;
  int _freshness_period, _ghost_period;
};


// a macro that complains (to the log) when a connection cannot be found.
#define CONNECTION_COMPLAINT(id, conn_table) { \
  FUNCTION(func); \
  conn_table.complain_missing_connection(id, function_name); \
}

// locates a connection by its "conn_id".  the "conn_table" must be a valid
// connection_table object.  after using the macro, a new bool variable named
// "conn_found" will be true if the connection was found.  not finding the
// connection causes a complaint to be emitted.
#define GET_CONN_ENTRY(conn_table, conn_id) \
  connection conn_entry; \
  bool conn_found = true; /* optimistic at first. */ \
  if (!conn_table.find(conn_id, conn_entry)) { \
    CONNECTION_COMPLAINT(conn_id, conn_table); \
    conn_found = false; /* pessimism prevails. */ \
  }

#endif

---