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_global_t const * manifest_global,
      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             : FD_PROTOTYPES_BEGIN
      70             : 
      71             : /* fd_snapshot_restore_{align,footprint} return required memory region
      72             :    parameters for the fd_snapshot_restore_t object. */
      73             : 
      74             : FD_FN_CONST ulong
      75             : fd_snapshot_restore_align( void );
      76             : 
      77             : FD_FN_CONST ulong
      78             : fd_snapshot_restore_footprint( void );
      79             : 
      80             : /* fd_snapshot_restore_new creates a restore object in the given memory
      81             :    region, which adheres to above alignment/footprint requirements.
      82             :    Returns qualified handle to object given restore object on success.
      83             : 
      84             :    spad is a bump allocator that outlives the snapshot restore
      85             :    object.  This allocator is used to buffer the serialized snapshot
      86             :    manifest (ca ~500 MB) and account data.
      87             : 
      88             :    The snapshot manifest is provided to the callback function.  This
      89             :    callback is invoked up to one time per restore object.  cb_manifest_ctx is an
      90             :    opaque pointer that is passed to the callback (and ignored by this
      91             :    API otherwise).  It is valid to provide a NULL cb_manifest_ctx.
      92             : 
      93             :    The status cache is also restored using the provided callback if
      94             :    a valid callback method is provided. It is valid to provide a NULL
      95             :    callback for testing purposes as of now, and the status_cache_ctx
      96             :    can also be NULL.
      97             : 
      98             :    Accounts are restored into the given account manager and funk
      99             :    transaction.  (Note that the restore process will leave behind
     100             :    "tombstone" account records that are invisible to fd_txn_account_init_from_funk_readonly,
     101             :    but do appear to fd_funk_get_acc_meta_readonly.)
     102             : 
     103             :    On failure, returns NULL.  Reasons for failure include invalid memory
     104             :    region.  Logs reasons for failure. */
     105             : 
     106             : fd_snapshot_restore_t *
     107             : fd_snapshot_restore_new( void *                                         mem,
     108             :                          fd_funk_t *                                    funk,
     109             :                          fd_funk_txn_t *                                txn,
     110             :                          fd_spad_t *                                    spad,
     111             :                          void *                                         cb_manifest_ctx,
     112             :                          fd_snapshot_restore_cb_manifest_fn_t           cb_manifest,
     113             :                          fd_snapshot_restore_cb_status_cache_fn_t       cb_status_cache );
     114             : 
     115             : /* fd_snapshot_restore_delete destroys the given restore object and
     116             :    frees any resources.  Returns allocated memory region back to
     117             :    caller. */
     118             : 
     119             : void *
     120             : fd_snapshot_restore_delete( fd_snapshot_restore_t * self );
     121             : 
     122             : /* fd_snapshot_restore_file provides a file to fd_snapshot_restore_t.
     123             :    restore is a fd_snapshot_restore_t pointer.  meta is the TAR file
     124             :    header of the file.  sz is the size of the file.  Suitable as a
     125             :    fd_tar_file_fn_t callback to fd_tar_reader. */
     126             : 
     127             : int
     128             : fd_snapshot_restore_file( void *                restore,
     129             :                           fd_tar_meta_t const * meta,
     130             :                           ulong                 sz );
     131             : 
     132             : /* fd_snapshot_restore_chunk provides a chunk of a file to
     133             :    fd_snapshot_restore_t.  restore is a fd_snapshot_restore_t pointer.
     134             :    [buf,buf+bufsz) is the memory region containing the file chunk.
     135             :    Suitable as a fd_tar_read_fn_t callback to fd_tar_reader. */
     136             : 
     137             : int
     138             : fd_snapshot_restore_chunk( void *       restore,
     139             :                            void const * buf,
     140             :                            ulong        bufsz );
     141             : 
     142             : /* fd_snapshot_restore_tar_vt implements fd_tar_read_vtable_t. */
     143             : 
     144             : ulong
     145             : fd_snapshot_restore_get_slot( fd_snapshot_restore_t * restore );
     146             : 
     147             : extern fd_tar_read_vtable_t const fd_snapshot_restore_tar_vt;
     148             : 
     149             : FD_PROTOTYPES_END
     150             : 
     151             : #endif /* HEADER_fd_src_flamenco_snapshot_fd_snapshot_restore_h */