Line data    Source code

       1             : #ifndef HEADER_fd_src_discof_restore_fd_ssping_h
       2             : #define HEADER_fd_src_discof_restore_fd_ssping_h
       3             : 
       4             : /* The snapshot pinger (ssping) is responsible for maintaining a list of
       5             :    peers that are reachable for snapshot download, and returning the
       6             :    "best" such peer at any time.
       7             : 
       8             :    The "best" peer is defined as the one with the lowest latency for
       9             :    now, in response to an ICMP ping request, although this should likely
      10             :    be changed to include snapshot age, or actual observed download speed
      11             :    for a small sample, or other factors.
      12             : 
      13             :    The snapshot pinger works on the assumption that there is a maximum
      14             :    size of peers that will ever be added, as we expect from the gossip
      15             :    system.  Peers can be added and removed arbitrarily outside of this
      16             :    maximum restriction. */
      17             : 
      18             : #include "../../../util/fd_util_base.h"
      19             : #include "../../../util/net/fd_net_headers.h"
      20             : 
      21           0 : #define FD_SSPING_ALIGN (8UL)
      22             : 
      23           0 : #define FD_SSPING_MAGIC (0xF17EDA2CE55A1A60) /* FIREDANCE SSPING V0 */
      24             : 
      25             : struct fd_ssping_private;
      26             : typedef struct fd_ssping_private fd_ssping_t;
      27             : 
      28             : FD_PROTOTYPES_BEGIN
      29             : 
      30             : FD_FN_CONST ulong
      31             : fd_ssping_align( void );
      32             : 
      33             : FD_FN_CONST ulong
      34             : fd_ssping_footprint( ulong max_peers );
      35             : 
      36             : void *
      37             : fd_ssping_new( void * shmem,
      38             :                ulong  max_peers,
      39             :                ulong  seed );
      40             : 
      41             : fd_ssping_t *
      42             : fd_ssping_join( void * shping );
      43             : 
      44             : /* Add a peer to be tracked by the snapshot pinger, which will from here
      45             :    until it is removed, constantly ping the node to maintain its
      46             :    status.
      47             : 
      48             :    An address can be added multiple times, and the addresses are
      49             :    internally reference counted, so it will need a corresponding number
      50             :    of releases to be removed from ping tracking.
      51             : 
      52             :    The ping tracker cannot be overflowed, and if too many peers are
      53             :    being tracked, trying to add a new peer is a no-op. */
      54             : 
      55             : void
      56             : fd_ssping_add( fd_ssping_t * ssping,
      57             :                fd_ip4_port_t addr );
      58             : 
      59             : /* Remove a peer from tracking by the snapshot pinger.  Peers are
      60             :    reference counted, so this will only remove the peer only if the
      61             :    count goes to zero.  If the peer is not tracked, this is a no-op. */
      62             : 
      63             : void
      64             : fd_ssping_remove( fd_ssping_t * ssping,
      65             :                   fd_ip4_port_t addr );
      66             : 
      67             : /* Mark the peer as invalid for selection for a period of time, probably
      68             :    if they refused a connection or served us a bad snapshot. */
      69             : 
      70             : void
      71             : fd_ssping_invalidate( fd_ssping_t * ssping,
      72             :                       fd_ip4_port_t addr,
      73             :                       long          now );
      74             : 
      75             : /* Advance the ping tracker forward in time until "now".  This should be
      76             :    called periodically to refresh pings and service networking to
      77             :    maintain ping states. */
      78             : 
      79             : void
      80             : fd_ssping_advance( fd_ssping_t * ssping,
      81             :                    long          now );
      82             : 
      83             : /* Retrieve the best "active" peer right now, by lowest ping.  If no
      84             :    peer is active or pingable, this returns 0.0.0.0:0. */
      85             : 
      86             : fd_ip4_port_t
      87             : fd_ssping_best( fd_ssping_t const * ssping );
      88             : 
      89             : FD_PROTOTYPES_END
      90             : 
      91             : #endif /* HEADER_fd_src_discof_restore_fd_ssping_h */