src/mesh/mesh_tunnel_tree.h

   1 /*
   2      This file is part of GNUnet.
   3      (C) 2001 - 2011 Christian Grothoff (and other contributing authors)
   4
   5      GNUnet is free software; you can redistribute it and/or modify
   6      it under the terms of the GNU General Public License as published
   7      by the Free Software Foundation; either version 3, or (at your
   8      option) any later version.
   9
  10      GNUnet is distributed in the hope that it will be useful, but
  11      WITHOUT ANY WARRANTY; without even the implied warranty of
  12      MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13      General Public License for more details.
  14
  15      You should have received a copy of the GNU General Public License
  16      along with GNUnet; see the file COPYING.  If not, write to the
  17      Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  18      Boston, MA 02111-1307, USA.
  19 */
  20
  21 /**
  22  * @file mesh/mesh_tree_tree.h
  23  * @brief Tunnel tree handling functions
  24  * @author Bartlomiej Polot
  25  */
  26
  27 #include "mesh.h"
  28
  29 /******************************************************************************/
  30 /************************      DATA STRUCTURES     ****************************/
  31 /******************************************************************************/
  32
  33 /**
  34  * Information regarding a possible path to reach a single peer
  35  */
  36 struct MeshPeerPath
  37 {
  38
  39     /**
  40      * Linked list
  41      */
  42   struct MeshPeerPath *next;
  43   struct MeshPeerPath *prev;
  44
  45     /**
  46      * List of all the peers that form the path from origin to target.
  47      */
  48   GNUNET_PEER_Id *peers;
  49
  50     /**
  51      * Number of peers (hops) in the path
  52      */
  53   unsigned int length;
  54
  55 };
  56
  57
  58 /**
  59  * Node of path tree for a tunnel
  60  */
  61 struct MeshTunnelTreeNode
  62 {
  63   /**
  64    * Tunnel this node belongs to (and therefore tree)
  65    */
  66   struct MeshTunnel *t;
  67
  68   /**
  69    * Peer this node describes
  70    */
  71   GNUNET_PEER_Id peer;
  72
  73   /**
  74    * Parent node in the tree
  75    */
  76   struct MeshTunnelTreeNode *parent;
  77
  78   /**
  79    * DLL of siblings
  80    */
  81   struct MeshTunnelTreeNode *next;
  82
  83   /**
  84    * DLL of siblings
  85    */
  86   struct MeshTunnelTreeNode *prev;
  87
  88   /**
  89    * DLL of children
  90    */
  91   struct MeshTunnelTreeNode *children_head;
  92
  93   /**
  94    * DLL of children
  95    */
  96   struct MeshTunnelTreeNode *children_tail;
  97
  98     /**
  99      * Status of the peer in the tunnel
 100      */
 101   enum MeshPeerState status;
 102 };
 103
 104
 105 /**
 106  * Tree to reach all peers in the tunnel
 107  */
 108 struct MeshTunnelTree
 109 {
 110   /**
 111    * How often to refresh the path
 112    */
 113   struct GNUNET_TIME_Relative refresh;
 114
 115   /**
 116    * Tunnel this path belongs to
 117    */
 118   struct MeshTunnel *t;
 119
 120   /**
 121    * Root node of peer tree
 122    */
 123   struct MeshTunnelTreeNode *root;
 124
 125   /**
 126    * Node that represents our position in the tree (for non local tunnels)
 127    */
 128   struct MeshTunnelTreeNode *me;
 129
 130   /**
 131    * DLL of disconneted nodes
 132    */
 133   struct MeshTunnelTreeNode *disconnected_head;
 134
 135   /**
 136    * DLL of disconneted nodes
 137    */
 138   struct MeshTunnelTreeNode *disconnected_tail;
 139
 140   /**
 141    * Cache of all peers and the first hop to them.
 142    * Indexed by PeerIdentity, contains a pointer to the PeerIdentity
 143    * of 1st hop.
 144    */
 145   struct GNUNET_CONTAINER_MultiHashMap *first_hops;
 146
 147 };
 148
 149
 150 /******************************************************************************/
 151 /*************************        FUNCTIONS       *****************************/
 152 /******************************************************************************/
 153
 154 /**
 155  * Create a new path
 156  *
 157  * @param lenght How many hops will the path have.
 158  *
 159  * @return A newly allocated path with a peer array of the specified length.
 160  */
 161 struct MeshPeerPath *
 162 path_new (unsigned int length);
 163
 164
 165 /**
 166  * Invert the path
 167  *
 168  * @param p the path to invert
 169  */
 170 void
 171 path_invert (struct MeshPeerPath *p);
 172
 173
 174 /**
 175  * Duplicate a path, incrementing short peer's rc.
 176  *
 177  * @param p The path to duplicate.
 178  */
 179 struct MeshPeerPath *
 180 path_duplicate (struct MeshPeerPath *path);
 181
 182
 183 /**
 184  * Find the first peer whom to send a packet to go down this path
 185  *
 186  * @param t The tunnel tree to use
 187  * @param peer The peerinfo of the peer we are trying to reach
 188  *
 189  * @return peerinfo of the peer who is the first hop in the tunnel
 190  *         NULL on error
 191  */
 192 struct GNUNET_PeerIdentity *
 193 path_get_first_hop (struct MeshTunnelTree *t,
 194                     GNUNET_PEER_Id peer);
 195
 196
 197 /**
 198  * Get the length of a path
 199  *
 200  * @param p The path to measure, with the local peer at any point of it
 201  *
 202  * @return Number of hops to reach destination
 203  *         UINT_MAX in case the peer is not in the path
 204  */
 205 unsigned int
 206 path_get_length (struct MeshPeerPath *p);
 207
 208
 209 /**
 210  * Get the cost of the path relative to the already built tunnel tree
 211  *
 212  * @param t The tunnel tree to which compare
 213  * @param path The individual path to reach a peer
 214  *
 215  * @return Number of hops to reach destination, UINT_MAX in case the peer is not
 216  * in the path
 217  */
 218 unsigned int
 219 path_get_cost (struct MeshTunnelTree *t,
 220                struct MeshPeerPath *path);
 221
 222
 223 /**
 224  * Destroy the path and free any allocated resources linked to it
 225  *
 226  * @param p the path to destroy
 227  *
 228  * @return GNUNET_OK on success
 229  */
 230 int
 231 path_destroy (struct MeshPeerPath *p);
 232
 233
 234 /******************************************************************************/
 235
 236 /**
 237  * Method called whenever a node has been marked as disconnected.
 238  *
 239  * @param node peer identity the tunnel stopped working with
 240  */
 241 typedef void (*MeshNodeDisconnectCB) (const struct MeshTunnelTreeNode * node);
 242
 243
 244 /**
 245  * Create a new tunnel tree associated to a tunnel
 246  *
 247  * @param t Tunnel this tree will represent
 248  * @param peer A short peer id of the root of the tree
 249  *
 250  * @return A newly allocated and initialized tunnel tree
 251  */
 252 struct MeshTunnelTree *
 253 tree_new (struct MeshTunnel *t, GNUNET_PEER_Id peer);
 254
 255
 256 /**
 257  * Recursively find the given peer in the tree.
 258  *
 259  * @param parent Parent node where to start looking.
 260  * @param peer Short ID of peer to find.
 261  *
 262  * @return Pointer to the node of the peer. NULL if not found.
 263  */
 264 struct MeshTunnelTreeNode *
 265 tree_find_peer (struct MeshTunnelTreeNode *parent,
 266                 GNUNET_PEER_Id peer);
 267
 268
 269 /**
 270  * Recusively update the info about what is the first hop to reach the node
 271  *
 272  * @param tree Tree this nodes belongs to
 273  * @param parent Node to be start updating
 274  * @param hop If known, ID of the first hop.
 275  *            If not known, NULL to find out and pass on children.
 276  */
 277 void
 278 tree_update_first_hops (struct MeshTunnelTree *tree,
 279                         struct MeshTunnelTreeNode *parent,
 280                         struct GNUNET_PeerIdentity *hop);
 281
 282 /**
 283  * Delete the current path to the peer, including all now unused relays.
 284  * The destination peer is NOT destroyed, it is returned in order to either set
 285  * a new path to it or destroy it explicitly, taking care of it's child nodes.
 286  *
 287  * @param t Tunnel tree where to delete the path from.
 288  * @param peer Destination peer whose path we want to remove.
 289  * @param cb Callback to use to notify about which peers are going to be
 290  *           disconnected.
 291  *
 292  * @return pointer to the pathless node.
 293  *         NULL when not found
 294  */
 295 struct MeshTunnelTreeNode *
 296 tree_del_path (struct MeshTunnelTree *t,
 297                GNUNET_PEER_Id peer,
 298                MeshNodeDisconnectCB cb);
 299
 300
 301 /**
 302  * Return a newly allocated individual path to reach a peer from the local peer,
 303  * according to the path tree of some tunnel.
 304  *
 305  * @param t Tunnel from which to read the path tree
 306  * @param peer Destination peer to whom we want a path
 307  *
 308  * @return A newly allocated individual path to reach the destination peer.
 309  *         Path must be destroyed afterwards.
 310  */
 311 struct MeshPeerPath *
 312 tree_get_path_to_peer(struct MeshTunnelTree *t,
 313                       GNUNET_PEER_Id peer);
 314
 315
 316 /**
 317  * Integrate a stand alone path into the tunnel tree.
 318  *
 319  * @param t Tunnel where to add the new path.
 320  * @param p Path to be integrated.
 321  * @param cb Callback to use to notify about peers temporarily disconnecting
 322  *
 323  * @return GNUNET_OK in case of success.
 324  *         GNUNET_SYSERR in case of error.
 325  */
 326 int
 327 tree_add_path (struct MeshTunnelTree *t,
 328                const struct MeshPeerPath *p,
 329                MeshNodeDisconnectCB cb);
 330
 331
 332 /**
 333  * Notifies a tree that a connection it might be using is broken.
 334  * Marks all peers down the paths as disconnected and notifies the client.
 335  *
 336  * @param t Tree to use.
 337  * @param p1 Short id of one of the peers (order unimportant)
 338  * @param p2 Short id of one of the peers (order unimportant)
 339  * @param cb Function to call for every peer that is marked as disconnected.
 340  *
 341  * @return Short ID of the first disconnected peer in the tree.
 342  */
 343 GNUNET_PEER_Id
 344 tree_notify_connection_broken (struct MeshTunnelTree *t,
 345                                GNUNET_PEER_Id p1,
 346                                GNUNET_PEER_Id p2,
 347                                MeshNodeDisconnectCB cb);
 348
 349
 350 /**
 351  * Deletes a peer from a tunnel, liberating all unused resources on the path to
 352  * it. It shouldn't have children, if it has they will be destroyed as well.
 353  * If the tree is not local and no longer has any paths, the root node will be
 354  * destroyed and marked as NULL.
 355  *
 356  * @param t Tunnel tree to use.
 357  * @param peer Short ID of the peer to remove from the tunnel tree.
 358  * @param cb Callback to notify client of disconnected peers.
 359  *
 360  * @return GNUNET_OK or GNUNET_SYSERR
 361  */
 362 int
 363 tree_del_peer (struct MeshTunnelTree *t,
 364                GNUNET_PEER_Id peer,
 365                MeshNodeDisconnectCB cb);
 366
 367 /**
 368  * Print the tree on stderr
 369  *
 370  * @param t The tree
 371  */
 372 void
 373 tree_debug(struct MeshTunnelTree *t);
 374
 375
 376 /**
 377  * Destroy the whole tree and free all used memory and Peer_Ids
 378  *
 379  * @param t Tree to be destroyed
 380  */
 381 void
 382 tree_destroy (struct MeshTunnelTree *t);