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