Line data    Source code

       1             : #ifndef HEADER_fd_src_discof_restore_utils_fd_ssping_h
       2             : #define HEADER_fd_src_discof_restore_utils_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             : struct fd_sspeer_selector_private;
      22             : typedef struct fd_sspeer_selector_private fd_sspeer_selector_t;
      23             : 
      24           0 : #define FD_SSPING_MAGIC (0xF17EDA2CE55A1A60) /* FIREDANCE SSPING V0 */
      25             : 
      26             : struct fd_ssping_private;
      27             : typedef struct fd_ssping_private fd_ssping_t;
      28             : 
      29             : typedef void
      30             : (* fd_ssping_on_ping_fn_t)( void *        _ctx,
      31             :                             fd_ip4_port_t addr,
      32             :                             ulong         latency );
      33             : 
      34             : FD_PROTOTYPES_BEGIN
      35             : 
      36             : FD_FN_CONST ulong
      37             : fd_ssping_align( void );
      38             : 
      39             : FD_FN_CONST ulong
      40             : fd_ssping_footprint( ulong max_peers );
      41             : 
      42             : void *
      43             : fd_ssping_new( void *                 shmem,
      44             :                ulong                  max_peers,
      45             :                ulong                  seed,
      46             :                fd_ssping_on_ping_fn_t on_ping_cb,
      47             :                void *                 cb_arg );
      48             : 
      49             : fd_ssping_t *
      50             : fd_ssping_join( void * shping );
      51             : 
      52             : /* Add a peer to be tracked by the snapshot pinger, which will from here
      53             :    until it is removed, constantly ping the node to maintain its
      54             :    status.
      55             : 
      56             :    An address can be added multiple times, and the addresses are
      57             :    internally reference counted, so it will need a corresponding number
      58             :    of releases to be removed from ping tracking.
      59             : 
      60             :    The ping tracker cannot be overflowed, and if too many peers are
      61             :    being tracked, trying to add a new peer is a no-op. */
      62             : 
      63             : void
      64             : fd_ssping_add( fd_ssping_t * ssping,
      65             :                fd_ip4_port_t addr );
      66             : 
      67             : /* Remove a peer from tracking by the snapshot pinger.  Peers are
      68             :    reference counted, so this will only remove the peer only if the
      69             :    count goes to zero.  If the peer is not tracked, this is a no-op.
      70             :    Returns whether the peer was removed. */
      71             : 
      72             : int
      73             : fd_ssping_remove( fd_ssping_t * ssping,
      74             :                   fd_ip4_port_t addr );
      75             : 
      76             : /* Mark the peer as invalid for selection for a period of time, probably
      77             :    if they refused a connection or served us a bad snapshot. */
      78             : 
      79             : void
      80             : fd_ssping_invalidate( fd_ssping_t * ssping,
      81             :                       fd_ip4_port_t addr,
      82             :                       long          now );
      83             : 
      84             : /* Advance the ping tracker forward in time until "now".  This should be
      85             :    called periodically to refresh pings and service networking to
      86             :    maintain ping states.  Takes a handle to the peer selector to
      87             :    invalidate peers from both the pinger and the selector. */
      88             : 
      89             : void
      90             : fd_ssping_advance( fd_ssping_t *          ssping,
      91             :                    long                   now,
      92             :                    fd_sspeer_selector_t * selector);
      93             : 
      94             : /* Return the ping socket file descriptor */
      95             : 
      96             : int
      97             : fd_ssping_get_sockfd( fd_ssping_t const * ssping );
      98             : 
      99             : FD_PROTOTYPES_END
     100             : 
     101             : #endif /* HEADER_fd_src_discof_restore_utils_fd_ssping_h */