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