Line data    Source code

       1             : #ifndef HEADER_fd_src_flamenco_snapshot_fd_snapshot_restore_h
       2             : #define HEADER_fd_src_flamenco_snapshot_fd_snapshot_restore_h
       3             : 
       4             : /* fd_snapshot_restore.h provides APIs for the downstream part of the
       5             :    snapshot loading pipeline.
       6             : 
       7             :      read => unzstd => untar => restore
       8             :                                 ^^^^^^^
       9             : 
      10             :    This header provides APIs for restoring an execution context from the
      11             :    individual snapshot files.  (The outer layers, such as the TAR stream
      12             :    and Zstandard compression, are managed by fd_snapshot_load).
      13             : 
      14             :    The snapshot format contains complex data structures without size
      15             :    restrictions.  This API will effectively make an unbounded amount of
      16             :    heap allocations while loading a snapshot. */
      17             : 
      18             : #include "fd_snapshot_base.h"
      19             : #include "../../util/archive/fd_tar.h"
      20             : #include "../runtime/context/fd_exec_slot_ctx.h"
      21             : 
      22             : /* We want to exit out of snapshot loading once the manifest has been loaded in.
      23             :    Once it has been seen, we don't want to exit out of snapshot loading if we
      24             :    have already done so once. We exit out to allow for manifest data to be used
      25             :    around the codebase. */
      26             : 
      27           6 : #define MANIFEST_DONE          (INT_MAX)
      28         864 : #define MANIFEST_DONE_NOT_SEEN (1)
      29          48 : #define MANIFEST_DONE_SEEN     (2)
      30             : 
      31             : /* fd_snapshot_restore_t implements a streaming TAR reader that parses
      32             :    archive records on the fly.  Records include the manifest (at the
      33             :    start of the file), and account data.  Notably, this object does on-
      34             :    the-fly heap allocations. */
      35             : 
      36             : struct fd_snapshot_restore;
      37             : typedef struct fd_snapshot_restore fd_snapshot_restore_t;
      38             : 
      39             : /* fd_snapshot_restore_cb_manifest_fn_t is a callback that provides the
      40             :    user of snapshot restore with the deserialized manifest.  The caller
      41             :    may move out data from the manifest (by zeroing out the fields that
      42             :    data was moved out from).  The lifetime of these moved values is
      43             :    that of the memory allocator in fd_snapshot_restore_new.  Any
      44             :    leftover fields will be freed on return.  The caller is responsible
      45             :    for freeing any moved objects even when returning an error.
      46             : 
      47             :    ctx is the pointer provided to fd_snapshot_restore_set_cb_manifest.
      48             :    Returns 0 on success.  Non-zero return value implies failure.  The
      49             :    return value gets forwarded to the original caller of the restore
      50             :    API. */
      51             : 
      52             : typedef int
      53             : (* fd_snapshot_restore_cb_manifest_fn_t)( void *                 ctx,
      54             :                                           fd_solana_manifest_t * manifest,
      55             :                                           fd_spad_t *            spad );
      56             : 
      57             : /* fd_snapshot_restore_cb_status_cache_fn_t is a callback that provides the
      58             :    user of snapshot restore with the deserialized slot deltas.  The caller
      59             :    may copy data from the deltas. Any leftover fields will be freed on return.
      60             : 
      61             :    ctx is the pointer provided to fd_snapshot_restore_set_cb_status_cache.
      62             :    Returns 0 on success.  Non-zero return value implies failure.  The
      63             :    return value gets forwarded to the original caller of the restore
      64             :    API. */
      65             : typedef int
      66             : (* fd_snapshot_restore_cb_status_cache_fn_t)( void *                  ctx,
      67             :                                               fd_bank_slot_deltas_t * slot_deltas,
      68             :                                               fd_spad_t *             spad );
      69             : 
      70             : typedef int
      71             : (* fd_snapshot_restore_cb_rent_fresh_account_fn_t)( fd_exec_slot_ctx_t * slot_ctx,
      72             :                                                     fd_pubkey_t const *  pubkey );
      73             : 
      74             : FD_PROTOTYPES_BEGIN
      75             : 
      76             : /* fd_snapshot_restore_{align,footprint} return required memory region
      77             :    parameters for the fd_snapshot_restore_t object. */
      78             : 
      79             : FD_FN_CONST ulong
      80             : fd_snapshot_restore_align( void );
      81             : 
      82             : FD_FN_CONST ulong
      83             : fd_snapshot_restore_footprint( void );
      84             : 
      85             : /* fd_snapshot_restore_new creates a restore object in the given memory
      86             :    region, which adheres to above alignment/footprint requirements.
      87             :    Returns qualified handle to object given restore object on success.
      88             : 
      89             :    spad is a bump allocator that outlives the snapshot restore
      90             :    object.  This allocator is used to buffer the serialized snapshot
      91             :    manifest (ca ~500 MB) and account data.
      92             : 
      93             :    The snapshot manifest is provided to the callback function.  This
      94             :    callback is invoked up to one time per restore object.  cb_manifest_ctx is an
      95             :    opaque pointer that is passed to the callback (and ignored by this
      96             :    API otherwise).  It is valid to provide a NULL cb_manifest_ctx.
      97             : 
      98             :    The status cache is also restored using the provided callback if
      99             :    a valid callback method is provided. It is valid to provide a NULL
     100             :    callback for testing purposes as of now, and the status_cache_ctx
     101             :    can also be NULL.
     102             : 
     103             :    Accounts are restored into the given account manager and funk
     104             :    transaction.  (Note that the restore process will leave behind
     105             :    "tombstone" account records that are invisible to fd_acc_mgr_view,
     106             :    but do appear to fd_acc_mgr_view_raw.)
     107             : 
     108             :    On failure, returns NULL.  Reasons for failure include invalid memory
     109             :    region.  Logs reasons for failure. */
     110             : 
     111             : fd_snapshot_restore_t *
     112             : fd_snapshot_restore_new( void *                                         mem,
     113             :                          fd_acc_mgr_t *                                 acc_mgr,
     114             :                          fd_funk_txn_t *                                txn,
     115             :                          fd_spad_t *                                    spad,
     116             :                          void *                                         cb_manifest_ctx,
     117             :                          fd_snapshot_restore_cb_manifest_fn_t           cb_manifest,
     118             :                          fd_snapshot_restore_cb_status_cache_fn_t       cb_status_cache,
     119             :                          fd_snapshot_restore_cb_rent_fresh_account_fn_t cb_rent_fresh_account );
     120             : 
     121             : /* fd_snapshot_restore_delete destroys the given restore object and
     122             :    frees any resources.  Returns allocated memory region back to
     123             :    caller. */
     124             : 
     125             : void *
     126             : fd_snapshot_restore_delete( fd_snapshot_restore_t * self );
     127             : 
     128             : /* fd_snapshot_restore_file provides a file to fd_snapshot_restore_t.
     129             :    restore is a fd_snapshot_restore_t pointer.  meta is the TAR file
     130             :    header of the file.  sz is the size of the file.  Suitable as a
     131             :    fd_tar_file_fn_t callback to fd_tar_reader. */
     132             : 
     133             : int
     134             : fd_snapshot_restore_file( void *                restore,
     135             :                           fd_tar_meta_t const * meta,
     136             :                           ulong                 sz );
     137             : 
     138             : /* fd_snapshot_restore_chunk provides a chunk of a file to
     139             :    fd_snapshot_restore_t.  restore is a fd_snapshot_restore_t pointer.
     140             :    [buf,buf+bufsz) is the memory region containing the file chunk.
     141             :    Suitable as a fd_tar_read_fn_t callback to fd_tar_reader. */
     142             : 
     143             : int
     144             : fd_snapshot_restore_chunk( void *       restore,
     145             :                            void const * buf,
     146             :                            ulong        bufsz );
     147             : 
     148             : /* fd_snapshot_restore_tar_vt implements fd_tar_read_vtable_t. */
     149             : 
     150             : ulong
     151             : fd_snapshot_restore_get_slot( fd_snapshot_restore_t * restore );
     152             : 
     153             : extern fd_tar_read_vtable_t const fd_snapshot_restore_tar_vt;
     154             : 
     155             : FD_PROTOTYPES_END
     156             : 
     157             : #endif /* HEADER_fd_src_flamenco_snapshot_fd_snapshot_restore_h */