Line data    Source code

       1             : #ifndef HEADER_fd_src_discof_restore_utils_fd_sspeer_selector_h
       2             : #define HEADER_fd_src_discof_restore_utils_fd_sspeer_selector_h
       3             : 
       4             : /* The snapshot peer selector (sspeer_selector) continuously selects
       5             :    the most optimal snapshot peer to download snapshots from.  The
       6             :    most optimal peer is defined as the closest peer that serves the
       7             :    most recent snapshot. */
       8             : 
       9             : #include "../../../util/fd_util_base.h"
      10             : #include "../../../util/net/fd_net_headers.h"
      11             : 
      12           3 : #define FD_SSPEER_SELECTOR_MAGIC (0xF17EDA2CE5593350) /* FIREDANCE SSPING V0 */
      13             : 
      14             : /* fd_sscluster_slot stores the highest full and incremental slot pair
      15             :    seen in the cluster. */
      16             : struct fd_sscluster_slot {
      17             :   ulong full;
      18             :   ulong incremental;
      19             : };
      20             : 
      21             : typedef struct fd_sscluster_slot fd_sscluster_slot_t;
      22             : 
      23             :  /* fd_sspeer_t represents a selected peer from the snapshot peer
      24             :     selector, including the peer's address, resolved snapshot slots,
      25             :     and selector score. */
      26             : struct fd_sspeer {
      27             :   fd_ip4_port_t addr;      /* address of the peer */
      28             :   ulong         full_slot;
      29             :   ulong         incr_slot;
      30             :   ulong         score;    /* selector score of peer */
      31             : };
      32             : 
      33             : typedef struct fd_sspeer fd_sspeer_t;
      34             : 
      35             : struct fd_sspeer_selector_private;
      36             : typedef struct fd_sspeer_selector_private fd_sspeer_selector_t;
      37             : 
      38             : FD_PROTOTYPES_BEGIN
      39             : 
      40             : FD_FN_CONST ulong
      41             : fd_sspeer_selector_align( void );
      42             : 
      43             : FD_FN_CONST ulong
      44             : fd_sspeer_selector_footprint( ulong max_peers );
      45             : 
      46             : void *
      47             : fd_sspeer_selector_new( void * shmem,
      48             :                         ulong  max_peers,
      49             :                         int    incremental_snapshot_fetch,
      50             :                         ulong  seed );
      51             : 
      52             : fd_sspeer_selector_t *
      53             : fd_sspeer_selector_join( void * shselector );
      54             : 
      55             : void *
      56             : fd_sspeer_selector_leave( fd_sspeer_selector_t * selector );
      57             : 
      58             : void *
      59             : fd_sspeer_selector_delete( void * shselector );
      60             : 
      61             : /* Add a peer to the selector.  If the peer already exists,
      62             :    fd_sspeer_selector_add updates the existing peer's score using the
      63             :    given peer latency and snapshot info.  Returns the updated score. */
      64             : ulong
      65             : fd_sspeer_selector_add( fd_sspeer_selector_t * selector,
      66             :                         fd_ip4_port_t          addr,
      67             :                         ulong                  peer_latency,
      68             :                         ulong                  full_slot,
      69             :                         ulong                  incr_slot );
      70             : 
      71             : /* Remove a peer from the selector.  Peers are removed when they are
      72             :    not reachable or serving corrupted/malformed snapshots.  This is a
      73             :    no-op if the peer does not exist in the selector.  */
      74             : void
      75             : fd_sspeer_selector_remove( fd_sspeer_selector_t * selector,
      76             :                            fd_ip4_port_t          addr );
      77             : 
      78             : /* Select the best peer to download a snapshot from.  incremental
      79             :    indicates to select a peer to download an incremental snapshot.  If
      80             :    incremental is set, base_slot must be a valid full snapshot slot. */
      81             : fd_sspeer_t
      82             : fd_sspeer_selector_best( fd_sspeer_selector_t * selector,
      83             :                          int                    incremental,
      84             :                          ulong                  base_slot );
      85             : 
      86             : /* Updates the selector's internal cluster slot and re-score all peers
      87             :    when the cluster slot updates (moves forward) */
      88             : void
      89             : fd_sspeer_selector_process_cluster_slot( fd_sspeer_selector_t * selector,
      90             :                                          ulong                  full_slot,
      91             :                                          ulong                  incr_slot );
      92             : 
      93             : /* Obtain the cluster slot from the selector.  It is the highest
      94             :    resolved full/incremental slot pair seen from snapshot hashes or
      95             :    from resolved http peers. */
      96             : fd_sscluster_slot_t
      97             : fd_sspeer_selector_cluster_slot( fd_sspeer_selector_t * selector );
      98             : 
      99             : FD_PROTOTYPES_END
     100             : 
     101             : #endif /* HEADER_fd_src_discof_restore_utils_fd_sspeer_selector_h */