Line data    Source code

       1             : #ifndef HEADER_fd_src_flamenco_runtime_fd_txn_account_h
       2             : #define HEADER_fd_src_flamenco_runtime_fd_txn_account_h
       3             : 
       4             : #include "../../ballet/txn/fd_txn.h"
       5             : #include "../fd_flamenco_base.h"
       6             : #include "program/fd_program_util.h"
       7             : #include "fd_executor_err.h"
       8             : #include "../types/fd_types.h"
       9             : #include "../../funk/fd_funk_rec.h"
      10             : 
      11             : struct fd_acc_mgr;
      12             : typedef struct fd_acc_mgr fd_acc_mgr_t;
      13             : 
      14             : /* fd_txn_account_t is a wrapper around a database record. It is used to
      15             :    provide an interface for an account during transaction execution
      16             :    along with reference counting semantics. The fd_txn_account_t object
      17             :    is initialized with a pointer to the account's metadata and data, the
      18             :    wksp that the data belongs to, its pubkey, and if the transaction
      19             :    account is mutable.
      20             : 
      21             :    fd_txn_account_t is NOT thread-safe and only supports a single join
      22             :    at a given time.
      23             : 
      24             :    TODO: Consider changing the meta/data boundary to make it more
      25             :    explicit that the caller passes in a contigious region of memory
      26             :    which has to correspond to the meta/data layout.
      27             : 
      28             :    TODO: Consider making the fd_txn_account struct private */
      29             : 
      30             : struct __attribute__((aligned(8UL))) fd_txn_account {
      31             :   ulong                           magic;
      32             : 
      33             :   fd_pubkey_t                     pubkey[1];
      34             : 
      35             :   fd_account_meta_t *             meta;
      36             :   uchar *                         data;
      37             : 
      38             :   int                             is_mutable;
      39             :   long                            meta_soff;
      40             : 
      41             :   ulong                           starting_dlen;
      42             :   ulong                           starting_lamports;
      43             : 
      44             :   /* Provide borrowing semantics. Used for single-threaded logic only,
      45             :      thus not comparable to a data synchronization lock. */
      46             :   ushort                          refcnt_excl;
      47             : 
      48             : };
      49             : typedef struct fd_txn_account fd_txn_account_t;
      50           3 : #define FD_TXN_ACCOUNT_FOOTPRINT (sizeof(fd_txn_account_t))
      51           3 : #define FD_TXN_ACCOUNT_ALIGN     (8UL)
      52        1050 : #define FD_TXN_ACCOUNT_MAGIC     (0xF15EDF1C51F51AA1UL)
      53             : 
      54        4719 : #define FD_TXN_ACCOUNT_DECL(_x)  fd_txn_account_t _x[1];
      55             : 
      56             : FD_PROTOTYPES_BEGIN
      57             : 
      58             : /* fd_txn_account_new lays out the memory required for a
      59             :    fd_txn_account object. The caller should only use the struct
      60             :    after it has been joined. fd_txn_account_t makes the assumption
      61             :    that the account data is laid out directly after the account meta.
      62             :    After a successful call to fd_txn_account_new, the object will now
      63             :    own the account's metadata and data. */
      64             : 
      65             : void *
      66             : fd_txn_account_new( void *              mem,
      67             :                     fd_pubkey_t const * pubkey,
      68             :                     fd_account_meta_t * meta,
      69             :                     int                 is_mutable );
      70             : 
      71             : /* fd_txn_account_join joins a thread with an indepedent address space
      72             :    to the memory region allocated by fd_txn_account_new. There can be
      73             :    only ONE valid join per fd_txn_account_t object. If a _join is called
      74             :    from one thread, it is implied that the object is no longer valid
      75             :    on other threads.
      76             : 
      77             :    TODO: When the new db is introduced, the wksp argument should be
      78             :    removed in favor of using offsets into other data structures. */
      79             : 
      80             : fd_txn_account_t *
      81             : fd_txn_account_join( void * mem, fd_wksp_t * data_wksp );
      82             : 
      83             : /* fd_txn_account_leave leaves a current local join and returns a
      84             :    pointer to the underlying shared memory region. The fd_txn_account_t
      85             :    will still own the account's metadata and data. */
      86             : 
      87             : void *
      88             : fd_txn_account_leave( fd_txn_account_t * acct );
      89             : 
      90             : /* fd_txn_account_delete removes the memory layout for the
      91             :    fd_txn_account_t object. It returns a pointer to the underlying
      92             :    shared struct. Any attempts to join after a call to
      93             :    fd_txn_account_delete will fail. The account's metadata and data
      94             :    will be owned by the caller after the delete is called.  */
      95             : 
      96             : void *
      97             : fd_txn_account_delete( void * mem );
      98             : 
      99             : /* Factory constructors from funk.
     100             :    TODO: These need to be removed when a new db is introduced and either
     101             :    replaced with a new factory constructor or removed entirely in favor
     102             :    of the generic constructors defined above. */
     103             : 
     104             : /* fd_txn_account_init_from_funk_readonly initializes a fd_txn_account_t
     105             :    object with a readonly handle into its funk record.
     106             : 
     107             :    IMPORTANT: When we access the account metadata and data pointer later
     108             :    on in the execution pipeline, we assume that nothing else will change
     109             :    these.
     110             : 
     111             :    This is safe because we assume that we hold a read lock on the
     112             :    account, since we are inside a Solana transaction. */
     113             : 
     114             : int
     115             : fd_txn_account_init_from_funk_readonly( fd_txn_account_t *        acct,
     116             :                                         fd_pubkey_t const *       pubkey,
     117             :                                         fd_funk_t const *         funk,
     118             :                                         fd_funk_txn_xid_t const * xid );
     119             : 
     120             : /* fd_txn_account_init_from_funk_mutable initializes a fd_txn_account_t
     121             :    object with a mutable handle into its funk record.
     122             : 
     123             :    IMPORTANT: Cannot be called in the executor tile. */
     124             : 
     125             : int
     126             : fd_txn_account_init_from_funk_mutable( fd_txn_account_t *        acct,
     127             :                                        fd_pubkey_t const *       pubkey,
     128             :                                        fd_funk_t *               funk,
     129             :                                        fd_funk_txn_xid_t const * xid,
     130             :                                        int                       do_create,
     131             :                                        ulong                     min_data_sz,
     132             :                                        fd_funk_rec_prepare_t *   prepare_out );
     133             : 
     134             : /* Publishes the record contents of a mutable fd_txn_account_t object
     135             :    obtained from fd_txn_account_init_from_funk_mutable into funk
     136             :    if the record does not yet exist in the current funk txn.
     137             :    ie. the record was created / cloned from an ancestor funk txn
     138             :    by fd_txn_account_init_from_funk_mutable. */
     139             : 
     140             : void
     141             : fd_txn_account_mutable_fini( fd_txn_account_t *        acct,
     142             :                              fd_funk_t *               funk,
     143             :                              fd_funk_rec_prepare_t *   prepare );
     144             : 
     145             : /* Simple accesssors and mutators. */
     146             : 
     147             : fd_pubkey_t const *
     148             : fd_txn_account_get_owner( fd_txn_account_t const * acct );
     149             : 
     150             : fd_account_meta_t const *
     151             : fd_txn_account_get_meta( fd_txn_account_t const * acct );
     152             : 
     153             : uchar const *
     154             : fd_txn_account_get_data( fd_txn_account_t const * acct );
     155             : 
     156             : uchar *
     157             : fd_txn_account_get_data_mut( fd_txn_account_t const * acct );
     158             : 
     159             : ulong
     160             : fd_txn_account_get_data_len( fd_txn_account_t const * acct );
     161             : 
     162             : int
     163             : fd_txn_account_is_executable( fd_txn_account_t const * acct );
     164             : 
     165             : ulong
     166             : fd_txn_account_get_lamports( fd_txn_account_t const * acct );
     167             : 
     168             : ulong
     169             : fd_txn_account_get_rent_epoch( fd_txn_account_t const * acct );
     170             : 
     171             : void
     172             : fd_txn_account_set_meta( fd_txn_account_t * acct, fd_account_meta_t * meta );
     173             : 
     174             : void
     175             : fd_txn_account_set_executable( fd_txn_account_t * acct, int is_executable );
     176             : 
     177             : void
     178             : fd_txn_account_set_owner( fd_txn_account_t * acct, fd_pubkey_t const * owner );
     179             : 
     180             : void
     181             : fd_txn_account_set_lamports( fd_txn_account_t * acct, ulong lamports );
     182             : 
     183             : int
     184             : fd_txn_account_checked_add_lamports( fd_txn_account_t * acct, ulong lamports );
     185             : 
     186             : int
     187             : fd_txn_account_checked_sub_lamports( fd_txn_account_t * acct, ulong lamports );
     188             : 
     189             : void
     190             : fd_txn_account_set_data( fd_txn_account_t * acct,
     191             :                          void const *       data,
     192             :                          ulong              data_sz );
     193             : 
     194             : void
     195             : fd_txn_account_set_data_len( fd_txn_account_t * acct, ulong data_len );
     196             : 
     197             : void
     198             : fd_txn_account_set_slot( fd_txn_account_t * acct,
     199             :                          ulong              slot );
     200             : 
     201             : void
     202             : fd_txn_account_clear_owner( fd_txn_account_t * acct );
     203             : 
     204             : void
     205             : fd_txn_account_resize( fd_txn_account_t * acct, ulong dlen );
     206             : 
     207             : ushort
     208             : fd_txn_account_is_borrowed( fd_txn_account_t const * acct );
     209             : 
     210             : int
     211             : fd_txn_account_is_mutable( fd_txn_account_t const * acct );
     212             : 
     213             : int
     214             : fd_txn_account_is_readonly( fd_txn_account_t const * acct );
     215             : 
     216             : int
     217             : fd_txn_account_try_borrow_mut( fd_txn_account_t * acct );
     218             : 
     219             : void
     220             : fd_txn_account_drop( fd_txn_account_t * acct );
     221             : 
     222             : void
     223             : fd_txn_account_set_readonly( fd_txn_account_t * acct );
     224             : 
     225             : void
     226             : fd_txn_account_set_mutable( fd_txn_account_t * acct );
     227             : 
     228             : fd_solana_account_meta_t
     229             : fd_txn_account_get_solana_meta( fd_txn_account_t const * acct );
     230             : 
     231             : FD_PROTOTYPES_END
     232             : 
     233             : #endif /* HEADER_fd_src_flamenco_runtime_fd_txn_account_h */