smgr.c

Go to the documentation of this file.

/*-------------------------------------------------------------------------
 *
 * smgr.c
 *    public interface routines to storage manager switch.
 *
 * All file system operations on relations dispatch through these routines.
 * An SMgrRelation represents physical on-disk relation files that are open
 * for reading and writing.
 *
 * When a relation is first accessed through the relation cache, the
 * corresponding SMgrRelation entry is opened by calling smgropen(), and the
 * reference is stored in the relation cache entry.
 *
 * Accesses that don't go through the relation cache open the SMgrRelation
 * directly.  That includes flushing buffers from the buffer cache, as well as
 * all accesses in auxiliary processes like the checkpointer or the WAL redo
 * in the startup process.
 *
 * Operations like CREATE, DROP, ALTER TABLE also hold SMgrRelation references
 * independent of the relation cache.  They need to prepare the physical files
 * before updating the relation cache.
 *
 * There is a hash table that holds all the SMgrRelation entries in the
 * backend.  If you call smgropen() twice for the same rel locator, you get a
 * reference to the same SMgrRelation. The reference is valid until the end of
 * transaction.  This makes repeated access to the same relation efficient,
 * and allows caching things like the relation size in the SMgrRelation entry.
 *
 * At end of transaction, all SMgrRelation entries that haven't been pinned
 * are removed.  An SMgrRelation can hold kernel file system descriptors for
 * the underlying files, and we'd like to close those reasonably soon if the
 * file gets deleted.  The SMgrRelations references held by the relcache are
 * pinned to prevent them from being closed.
 *
 * There is another mechanism to close file descriptors early:
 * PROCSIGNAL_BARRIER_SMGRRELEASE.  It is a request to immediately close all
 * file descriptors.  Upon receiving that signal, the backend closes all file
 * descriptors held open by SMgrRelations, but because it can happen in the
 * middle of a transaction, we cannot destroy the SMgrRelation objects
 * themselves, as there could pointers to them in active use.  See
 * smgrrelease() and smgrreleaseall().
 *
 * NB: We need to hold interrupts across most of the functions in this file,
 * as otherwise interrupt processing, e.g. due to a < ERROR elog/ereport, can
 * trigger procsignal processing, which in turn can trigger
 * smgrreleaseall(). Most of the relevant code is not reentrant.  It seems
 * better to put the HOLD_INTERRUPTS()/RESUME_INTERRUPTS() here, instead of
 * trying to push them down to md.c where possible: For one, every smgr
 * implementation would be vulnerable, for another, a good bit of smgr.c code
 * itself is affected too.  Eventually we might want a more targeted solution,
 * allowing e.g. a networked smgr implementation to be interrupted, but many
 * other, more complicated, problems would need to be fixed for that to be
 * viable (e.g. smgr.c is often called with interrupts already held).
 *
 * Portions Copyright (c) 1996-2026, PostgreSQL Global Development Group
 * Portions Copyright (c) 1994, Regents of the University of California
 *
 *
 * IDENTIFICATION
 *    src/backend/storage/smgr/smgr.c
 *
 *-------------------------------------------------------------------------
 */
#include "postgres.h"
 
#include "access/xlogutils.h"
#include "lib/ilist.h"
#include "miscadmin.h"
#include "storage/aio.h"
#include "storage/bufmgr.h"
#include "storage/ipc.h"
#include "storage/md.h"
#include "storage/smgr.h"
#include "utils/hsearch.h"
#include "utils/inval.h"
 
 
/*
 * This struct of function pointers defines the API between smgr.c and
 * any individual storage manager module.  Note that smgr subfunctions are
 * generally expected to report problems via elog(ERROR).  An exception is
 * that smgr_unlink should use elog(WARNING), rather than erroring out,
 * because we normally unlink relations during post-commit/abort cleanup,
 * and so it's too late to raise an error.  Also, various conditions that
 * would normally be errors should be allowed during bootstrap and/or WAL
 * recovery --- see comments in md.c for details.
 */
typedef struct f_smgr
{
    void        (*smgr_init) (void);    /* may be NULL */
    void        (*smgr_shutdown) (void);    /* may be NULL */
    void        (*smgr_open) (SMgrRelation reln);
    void        (*smgr_close) (SMgrRelation reln, ForkNumber forknum);
    void        (*smgr_create) (SMgrRelation reln, ForkNumber forknum,
                                bool isRedo);
    bool        (*smgr_exists) (SMgrRelation reln, ForkNumber forknum);
    void        (*smgr_unlink) (RelFileLocatorBackend rlocator, ForkNumber forknum,
                                bool isRedo);
    void        (*smgr_extend) (SMgrRelation reln, ForkNumber forknum,
                                BlockNumber blocknum, const void *buffer, bool skipFsync);
    void        (*smgr_zeroextend) (SMgrRelation reln, ForkNumber forknum,
                                    BlockNumber blocknum, int nblocks, bool skipFsync);
    bool        (*smgr_prefetch) (SMgrRelation reln, ForkNumber forknum,
                                  BlockNumber blocknum, int nblocks);
    uint32      (*smgr_maxcombine) (SMgrRelation reln, ForkNumber forknum,
                                    BlockNumber blocknum);
    void        (*smgr_readv) (SMgrRelation reln, ForkNumber forknum,
                               BlockNumber blocknum,
                               void **buffers, BlockNumber nblocks);
    void        (*smgr_startreadv) (PgAioHandle *ioh,
                                    SMgrRelation reln, ForkNumber forknum,
                                    BlockNumber blocknum,
                                    void **buffers, BlockNumber nblocks);
    void        (*smgr_writev) (SMgrRelation reln, ForkNumber forknum,
                                BlockNumber blocknum,
                                const void **buffers, BlockNumber nblocks,
                                bool skipFsync);
    void        (*smgr_writeback) (SMgrRelation reln, ForkNumber forknum,
                                   BlockNumber blocknum, BlockNumber nblocks);
    BlockNumber (*smgr_nblocks) (SMgrRelation reln, ForkNumber forknum);
    void        (*smgr_truncate) (SMgrRelation reln, ForkNumber forknum,
                                  BlockNumber old_blocks, BlockNumber nblocks);
    void        (*smgr_immedsync) (SMgrRelation reln, ForkNumber forknum);
    void        (*smgr_registersync) (SMgrRelation reln, ForkNumber forknum);
    int         (*smgr_fd) (SMgrRelation reln, ForkNumber forknum, BlockNumber blocknum, uint32 *off);
} f_smgr;
 
static const f_smgr smgrsw[] = {
    /* magnetic disk */
    {
        .smgr_init = mdinit,
        .smgr_shutdown = NULL,
        .smgr_open = mdopen,
        .smgr_close = mdclose,
        .smgr_create = mdcreate,
        .smgr_exists = mdexists,
        .smgr_unlink = mdunlink,
        .smgr_extend = mdextend,
        .smgr_zeroextend = mdzeroextend,
        .smgr_prefetch = mdprefetch,
        .smgr_maxcombine = mdmaxcombine,
        .smgr_readv = mdreadv,
        .smgr_startreadv = mdstartreadv,
        .smgr_writev = mdwritev,
        .smgr_writeback = mdwriteback,
        .smgr_nblocks = mdnblocks,
        .smgr_truncate = mdtruncate,
        .smgr_immedsync = mdimmedsync,
        .smgr_registersync = mdregistersync,
        .smgr_fd = mdfd,
    }
};
 
static const int NSmgr = lengthof(smgrsw);
 
/*
 * Each backend has a hashtable that stores all extant SMgrRelation objects.
 * In addition, "unpinned" SMgrRelation objects are chained together in a list.
 */
static HTAB *SMgrRelationHash = NULL;
 
static dlist_head unpinned_relns;
 
/* local function prototypes */
static void smgrshutdown(int code, Datum arg);
static void smgrdestroy(SMgrRelation reln);
 
static void smgr_aio_reopen(PgAioHandle *ioh);
static char *smgr_aio_describe_identity(const PgAioTargetData *sd);
 
 
const PgAioTargetInfo aio_smgr_target_info = {
    .name = "smgr",
    .reopen = smgr_aio_reopen,
    .describe_identity = smgr_aio_describe_identity,
};
 
 
/*
 * smgrinit(), smgrshutdown() -- Initialize or shut down storage
 *                               managers.
 *
 * Note: smgrinit is called during backend startup (normal or standalone
 * case), *not* during postmaster start.  Therefore, any resources created
 * here or destroyed in smgrshutdown are backend-local.
 */
void
smgrinit(void)
{
    int         i;
 
    HOLD_INTERRUPTS();
 
    for (i = 0; i < NSmgr; i++)
    {
        if (smgrsw[i].smgr_init)
            smgrsw[i].smgr_init();
    }
 
    RESUME_INTERRUPTS();
 
    /* register the shutdown proc */
    on_proc_exit(smgrshutdown, 0);
}
 
/*
 * on_proc_exit hook for smgr cleanup during backend shutdown
 */
static void
smgrshutdown(int code, Datum arg)
{
    int         i;
 
    HOLD_INTERRUPTS();
 
    for (i = 0; i < NSmgr; i++)
    {
        if (smgrsw[i].smgr_shutdown)
            smgrsw[i].smgr_shutdown();
    }
 
    RESUME_INTERRUPTS();
}
 
/*
 * smgropen() -- Return an SMgrRelation object, creating it if need be.
 *
 * In versions of PostgreSQL prior to 17, this function returned an object
 * with no defined lifetime.  Now, however, the object remains valid for the
 * lifetime of the transaction, up to the point where AtEOXact_SMgr() is
 * called, making it much easier for callers to know for how long they can
 * hold on to a pointer to the returned object.  If this function is called
 * outside of a transaction, the object remains valid until smgrdestroy() or
 * smgrdestroyall() is called.  Background processes that use smgr but not
 * transactions typically do this once per checkpoint cycle.
 *
 * This does not attempt to actually open the underlying files.
 */
SMgrRelation
smgropen(RelFileLocator rlocator, ProcNumber backend)
{
    RelFileLocatorBackend brlocator;
    SMgrRelation reln;
    bool        found;
 
    Assert(RelFileNumberIsValid(rlocator.relNumber));
 
    HOLD_INTERRUPTS();
 
    if (SMgrRelationHash == NULL)
    {
        /* First time through: initialize the hash table */
        HASHCTL     ctl;
 
        ctl.keysize = sizeof(RelFileLocatorBackend);
        ctl.entrysize = sizeof(SMgrRelationData);
        SMgrRelationHash = hash_create("smgr relation table", 400,
                                       &ctl, HASH_ELEM | HASH_BLOBS);
        dlist_init(&unpinned_relns);
    }
 
    /* Look up or create an entry */
    brlocator.locator = rlocator;
    brlocator.backend = backend;
    reln = (SMgrRelation) hash_search(SMgrRelationHash,
                                      &brlocator,
                                      HASH_ENTER, &found);
 
    /* Initialize it if not present before */
    if (!found)
    {
        /* hash_search already filled in the lookup key */
        reln->smgr_targblock = InvalidBlockNumber;
        for (int i = 0; i <= MAX_FORKNUM; ++i)
            reln->smgr_cached_nblocks[i] = InvalidBlockNumber;
        reln->smgr_which = 0;   /* we only have md.c at present */
 
        /* it is not pinned yet */
        reln->pincount = 0;
        dlist_push_tail(&unpinned_relns, &reln->node);
 
        /* implementation-specific initialization */
        smgrsw[reln->smgr_which].smgr_open(reln);
    }
 
    RESUME_INTERRUPTS();
 
    return reln;
}
 
/*
 * smgrpin() -- Prevent an SMgrRelation object from being destroyed at end of
 *              transaction
 */
void
smgrpin(SMgrRelation reln)
{
    if (reln->pincount == 0)
        dlist_delete(&reln->node);
    reln->pincount++;
}
 
/*
 * smgrunpin() -- Allow an SMgrRelation object to be destroyed at end of
 *                transaction
 *
 * The object remains valid, but if there are no other pins on it, it is moved
 * to the unpinned list where it will be destroyed by AtEOXact_SMgr().
 */
void
smgrunpin(SMgrRelation reln)
{
    Assert(reln->pincount > 0);
    reln->pincount--;
    if (reln->pincount == 0)
        dlist_push_tail(&unpinned_relns, &reln->node);
}
 
/*
 * smgrdestroy() -- Delete an SMgrRelation object.
 */
static void
smgrdestroy(SMgrRelation reln)
{
    ForkNumber  forknum;
 
    Assert(reln->pincount == 0);
 
    HOLD_INTERRUPTS();
 
    for (forknum = 0; forknum <= MAX_FORKNUM; forknum++)
        smgrsw[reln->smgr_which].smgr_close(reln, forknum);
 
    dlist_delete(&reln->node);
 
    if (hash_search(SMgrRelationHash,
                    &(reln->smgr_rlocator),
                    HASH_REMOVE, NULL) == NULL)
        elog(ERROR, "SMgrRelation hashtable corrupted");
 
    RESUME_INTERRUPTS();
}
 
/*
 * smgrrelease() -- Release all resources used by this object.
 *
 * The object remains valid.
 */
void
smgrrelease(SMgrRelation reln)
{
    HOLD_INTERRUPTS();
 
    for (ForkNumber forknum = 0; forknum <= MAX_FORKNUM; forknum++)
    {
        smgrsw[reln->smgr_which].smgr_close(reln, forknum);
        reln->smgr_cached_nblocks[forknum] = InvalidBlockNumber;
    }
    reln->smgr_targblock = InvalidBlockNumber;
 
    RESUME_INTERRUPTS();
}
 
/*
 * smgrclose() -- Close an SMgrRelation object.
 *
 * The SMgrRelation reference should not be used after this call.  However,
 * because we don't keep track of the references returned by smgropen(), we
 * don't know if there are other references still pointing to the same object,
 * so we cannot remove the SMgrRelation object yet.  Therefore, this is just a
 * synonym for smgrrelease() at the moment.
 */
void
smgrclose(SMgrRelation reln)
{
    smgrrelease(reln);
}
 
/*
 * smgrdestroyall() -- Release resources used by all unpinned objects.
 *
 * It must be known that there are no pointers to SMgrRelations, other than
 * those pinned with smgrpin().
 */
void
smgrdestroyall(void)
{
    dlist_mutable_iter iter;
 
    /* seems unsafe to accept interrupts while in a dlist_foreach_modify() */
    HOLD_INTERRUPTS();
 
    /*
     * Zap all unpinned SMgrRelations.  We rely on smgrdestroy() to remove
     * each one from the list.
     */
    dlist_foreach_modify(iter, &unpinned_relns)
    {
        SMgrRelation rel = dlist_container(SMgrRelationData, node,
                                           iter.cur);
 
        smgrdestroy(rel);
    }
 
    RESUME_INTERRUPTS();
}
 
/*
 * smgrreleaseall() -- Release resources used by all objects.
 */
void
smgrreleaseall(void)
{
    HASH_SEQ_STATUS status;
    SMgrRelation reln;
 
    /* Nothing to do if hashtable not set up */
    if (SMgrRelationHash == NULL)
        return;
 
    /* seems unsafe to accept interrupts while iterating */
    HOLD_INTERRUPTS();
 
    hash_seq_init(&status, SMgrRelationHash);
 
    while ((reln = (SMgrRelation) hash_seq_search(&status)) != NULL)
    {
        smgrrelease(reln);
    }
 
    RESUME_INTERRUPTS();
}
 
/*
 * smgrreleaserellocator() -- Release resources for given RelFileLocator, if
 *                            it's open.
 *
 * This has the same effects as smgrrelease(smgropen(rlocator)), but avoids
 * uselessly creating a hashtable entry only to drop it again when no
 * such entry exists already.
 */
void
smgrreleaserellocator(RelFileLocatorBackend rlocator)
{
    SMgrRelation reln;
 
    /* Nothing to do if hashtable not set up */
    if (SMgrRelationHash == NULL)
        return;
 
    reln = (SMgrRelation) hash_search(SMgrRelationHash,
                                      &rlocator,
                                      HASH_FIND, NULL);
    if (reln != NULL)
        smgrrelease(reln);
}
 
/*
 * smgrexists() -- Does the underlying file for a fork exist?
 */
bool
smgrexists(SMgrRelation reln, ForkNumber forknum)
{
    bool        ret;
 
    HOLD_INTERRUPTS();
    ret = smgrsw[reln->smgr_which].smgr_exists(reln, forknum);
    RESUME_INTERRUPTS();
 
    return ret;
}
 
/*
 * smgrcreate() -- Create a new relation.
 *
 * Given an already-created (but presumably unused) SMgrRelation,
 * cause the underlying disk file or other storage for the fork
 * to be created.
 */
void
smgrcreate(SMgrRelation reln, ForkNumber forknum, bool isRedo)
{
    HOLD_INTERRUPTS();
    smgrsw[reln->smgr_which].smgr_create(reln, forknum, isRedo);
    RESUME_INTERRUPTS();
}
 
/*
 * smgrdosyncall() -- Immediately sync all forks of all given relations
 *
 * All forks of all given relations are synced out to the store.
 *
 * This is equivalent to FlushRelationBuffers() for each smgr relation,
 * then calling smgrimmedsync() for all forks of each relation, but it's
 * significantly quicker so should be preferred when possible.
 */
void
smgrdosyncall(SMgrRelation *rels, int nrels)
{
    int         i = 0;
    ForkNumber  forknum;
 
    if (nrels == 0)
        return;
 
    FlushRelationsAllBuffers(rels, nrels);
 
    HOLD_INTERRUPTS();
 
    /*
     * Sync the physical file(s).
     */
    for (i = 0; i < nrels; i++)
    {
        int         which = rels[i]->smgr_which;
 
        for (forknum = 0; forknum <= MAX_FORKNUM; forknum++)
        {
            if (smgrsw[which].smgr_exists(rels[i], forknum))
                smgrsw[which].smgr_immedsync(rels[i], forknum);
        }
    }
 
    RESUME_INTERRUPTS();
}
 
/*
 * smgrdounlinkall() -- Immediately unlink all forks of all given relations
 *
 * All forks of all given relations are removed from the store.  This
 * should not be used during transactional operations, since it can't be
 * undone.
 *
 * If isRedo is true, it is okay for the underlying file(s) to be gone
 * already.
 */
void
smgrdounlinkall(SMgrRelation *rels, int nrels, bool isRedo)
{
    int         i = 0;
    RelFileLocatorBackend *rlocators;
    ForkNumber  forknum;
 
    if (nrels == 0)
        return;
 
    /*
     * It would be unsafe to process interrupts between DropRelationBuffers()
     * and unlinking the underlying files. This probably should be a critical
     * section, but we're not there yet.
     */
    HOLD_INTERRUPTS();
 
    /*
     * Get rid of any remaining buffers for the relations.  bufmgr will just
     * drop them without bothering to write the contents.
     */
    DropRelationsAllBuffers(rels, nrels);
 
    /*
     * create an array which contains all relations to be dropped, and close
     * each relation's forks at the smgr level while at it
     */
    rlocators = palloc_array(RelFileLocatorBackend, nrels);
    for (i = 0; i < nrels; i++)
    {
        RelFileLocatorBackend rlocator = rels[i]->smgr_rlocator;
        int         which = rels[i]->smgr_which;
 
        rlocators[i] = rlocator;
 
        /* Close the forks at smgr level */
        for (forknum = 0; forknum <= MAX_FORKNUM; forknum++)
            smgrsw[which].smgr_close(rels[i], forknum);
    }
 
    /*
     * Send a shared-inval message to force other backends to close any
     * dangling smgr references they may have for these rels.  We should do
     * this before starting the actual unlinking, in case we fail partway
     * through that step.  Note that the sinval messages will eventually come
     * back to this backend, too, and thereby provide a backstop that we
     * closed our own smgr rel.
     */
    for (i = 0; i < nrels; i++)
        CacheInvalidateSmgr(rlocators[i]);
 
    /*
     * Delete the physical file(s).
     *
     * Note: smgr_unlink must treat deletion failure as a WARNING, not an
     * ERROR, because we've already decided to commit or abort the current
     * xact.
     */
 
    for (i = 0; i < nrels; i++)
    {
        int         which = rels[i]->smgr_which;
 
        for (forknum = 0; forknum <= MAX_FORKNUM; forknum++)
            smgrsw[which].smgr_unlink(rlocators[i], forknum, isRedo);
    }
 
    pfree(rlocators);
 
    RESUME_INTERRUPTS();
}
 
 
/*
 * smgrextend() -- Add a new block to a file.
 *
 * The semantics are nearly the same as smgrwrite(): write at the
 * specified position.  However, this is to be used for the case of
 * extending a relation (i.e., blocknum is at or beyond the current
 * EOF).  Note that we assume writing a block beyond current EOF
 * causes intervening file space to become filled with zeroes.
 */
void
smgrextend(SMgrRelation reln, ForkNumber forknum, BlockNumber blocknum,
           const void *buffer, bool skipFsync)
{
    HOLD_INTERRUPTS();
 
    smgrsw[reln->smgr_which].smgr_extend(reln, forknum, blocknum,
                                         buffer, skipFsync);
 
    /*
     * Normally we expect this to increase nblocks by one, but if the cached
     * value isn't as expected, just invalidate it so the next call asks the
     * kernel.
     */
    if (reln->smgr_cached_nblocks[forknum] == blocknum)
        reln->smgr_cached_nblocks[forknum] = blocknum + 1;
    else
        reln->smgr_cached_nblocks[forknum] = InvalidBlockNumber;
 
    RESUME_INTERRUPTS();
}
 
/*
 * smgrzeroextend() -- Add new zeroed out blocks to a file.
 *
 * Similar to smgrextend(), except the relation can be extended by
 * multiple blocks at once and the added blocks will be filled with
 * zeroes.
 */
void
smgrzeroextend(SMgrRelation reln, ForkNumber forknum, BlockNumber blocknum,
               int nblocks, bool skipFsync)
{
    HOLD_INTERRUPTS();
 
    smgrsw[reln->smgr_which].smgr_zeroextend(reln, forknum, blocknum,
                                             nblocks, skipFsync);
 
    /*
     * Normally we expect this to increase the fork size by nblocks, but if
     * the cached value isn't as expected, just invalidate it so the next call
     * asks the kernel.
     */
    if (reln->smgr_cached_nblocks[forknum] == blocknum)
        reln->smgr_cached_nblocks[forknum] = blocknum + nblocks;
    else
        reln->smgr_cached_nblocks[forknum] = InvalidBlockNumber;
 
    RESUME_INTERRUPTS();
}
 
/*
 * smgrprefetch() -- Initiate asynchronous read of the specified block of a relation.
 *
 * In recovery only, this can return false to indicate that a file
 * doesn't exist (presumably it has been dropped by a later WAL
 * record).
 */
bool
smgrprefetch(SMgrRelation reln, ForkNumber forknum, BlockNumber blocknum,
             int nblocks)
{
    bool        ret;
 
    HOLD_INTERRUPTS();
    ret = smgrsw[reln->smgr_which].smgr_prefetch(reln, forknum, blocknum, nblocks);
    RESUME_INTERRUPTS();
 
    return ret;
}
 
/*
 * smgrmaxcombine() - Return the maximum number of total blocks that can be
 *               combined with an IO starting at blocknum.
 *
 * The returned value includes the IO for blocknum itself.
 */
uint32
smgrmaxcombine(SMgrRelation reln, ForkNumber forknum,
               BlockNumber blocknum)
{
    uint32      ret;
 
    HOLD_INTERRUPTS();
    ret = smgrsw[reln->smgr_which].smgr_maxcombine(reln, forknum, blocknum);
    RESUME_INTERRUPTS();
 
    return ret;
}
 
/*
 * smgrreadv() -- read a particular block range from a relation into the
 *               supplied buffers.
 *
 * This routine is called from the buffer manager in order to
 * instantiate pages in the shared buffer cache.  All storage managers
 * return pages in the format that POSTGRES expects.
 *
 * If more than one block is intended to be read, callers need to use
 * smgrmaxcombine() to check how many blocks can be combined into one IO.
 */
void
smgrreadv(SMgrRelation reln, ForkNumber forknum, BlockNumber blocknum,
          void **buffers, BlockNumber nblocks)
{
    HOLD_INTERRUPTS();
    smgrsw[reln->smgr_which].smgr_readv(reln, forknum, blocknum, buffers,
                                        nblocks);
    RESUME_INTERRUPTS();
}
 
/*
 * smgrstartreadv() -- asynchronous version of smgrreadv()
 *
 * This starts an asynchronous readv IO using the IO handle `ioh`. Other than
 * `ioh` all parameters are the same as smgrreadv().
 *
 * Completion callbacks above smgr will be passed the result as the number of
 * successfully read blocks if the read [partially] succeeds (Buffers for
 * blocks not successfully read might bear unspecified modifications, up to
 * the full nblocks). This maintains the abstraction that smgr operates on the
 * level of blocks, rather than bytes.
 *
 * Compared to smgrreadv(), more responsibilities fall on the caller:
 * - Partial reads need to be handled by the caller re-issuing IO for the
 *   unread blocks
 * - smgr will ereport(LOG_SERVER_ONLY) some problems, but higher layers are
 *   responsible for pgaio_result_report() to mirror that news to the user (if
 *   the IO results in PGAIO_RS_WARNING) or abort the (sub)transaction (if
 *   PGAIO_RS_ERROR).
 * - Under Valgrind, the "buffers" memory may or may not change status to
 *   DEFINED, depending on io_method and concurrent activity.
 */
void
smgrstartreadv(PgAioHandle *ioh,
               SMgrRelation reln, ForkNumber forknum, BlockNumber blocknum,
               void **buffers, BlockNumber nblocks)
{
    HOLD_INTERRUPTS();
    smgrsw[reln->smgr_which].smgr_startreadv(ioh,
                                             reln, forknum, blocknum, buffers,
                                             nblocks);
    RESUME_INTERRUPTS();
}
 
/*
 * smgrwritev() -- Write the supplied buffers out.
 *
 * This is to be used only for updating already-existing blocks of a
 * relation (ie, those before the current EOF).  To extend a relation,
 * use smgrextend().
 *
 * This is not a synchronous write -- the block is not necessarily
 * on disk at return, only dumped out to the kernel.  However,
 * provisions will be made to fsync the write before the next checkpoint.
 *
 * NB: The mechanism to ensure fsync at next checkpoint assumes that there is
 * something that prevents a concurrent checkpoint from "racing ahead" of the
 * write.  One way to prevent that is by holding a lock on the buffer; the
 * buffer manager's writes are protected by that.  The bulk writer facility
 * in bulk_write.c checks the redo pointer and calls smgrimmedsync() if a
 * checkpoint happened; that relies on the fact that no other backend can be
 * concurrently modifying the page.
 *
 * skipFsync indicates that the caller will make other provisions to
 * fsync the relation, so we needn't bother.  Temporary relations also
 * do not require fsync.
 *
 * If more than one block is intended to be read, callers need to use
 * smgrmaxcombine() to check how many blocks can be combined into one IO.
 */
void
smgrwritev(SMgrRelation reln, ForkNumber forknum, BlockNumber blocknum,
           const void **buffers, BlockNumber nblocks, bool skipFsync)
{
    HOLD_INTERRUPTS();
    smgrsw[reln->smgr_which].smgr_writev(reln, forknum, blocknum,
                                         buffers, nblocks, skipFsync);
    RESUME_INTERRUPTS();
}
 
/*
 * smgrwriteback() -- Trigger kernel writeback for the supplied range of
 *                     blocks.
 */
void
smgrwriteback(SMgrRelation reln, ForkNumber forknum, BlockNumber blocknum,
              BlockNumber nblocks)
{
    HOLD_INTERRUPTS();
    smgrsw[reln->smgr_which].smgr_writeback(reln, forknum, blocknum,
                                            nblocks);
    RESUME_INTERRUPTS();
}
 
/*
 * smgrnblocks() -- Calculate the number of blocks in the
 *                  supplied relation.
 */
BlockNumber
smgrnblocks(SMgrRelation reln, ForkNumber forknum)
{
    BlockNumber result;
 
    /* Check and return if we get the cached value for the number of blocks. */
    result = smgrnblocks_cached(reln, forknum);
    if (result != InvalidBlockNumber)
        return result;
 
    HOLD_INTERRUPTS();
 
    result = smgrsw[reln->smgr_which].smgr_nblocks(reln, forknum);
 
    reln->smgr_cached_nblocks[forknum] = result;
 
    RESUME_INTERRUPTS();
 
    return result;
}
 
/*
 * smgrnblocks_cached() -- Get the cached number of blocks in the supplied
 *                         relation.
 *
 * Returns an InvalidBlockNumber when not in recovery and when the relation
 * fork size is not cached.
 */
BlockNumber
smgrnblocks_cached(SMgrRelation reln, ForkNumber forknum)
{
    /*
     * For now, this function uses cached values only in recovery due to lack
     * of a shared invalidation mechanism for changes in file size.  Code
     * elsewhere reads smgr_cached_nblocks and copes with stale data.
     */
    if (InRecovery && reln->smgr_cached_nblocks[forknum] != InvalidBlockNumber)
        return reln->smgr_cached_nblocks[forknum];
 
    return InvalidBlockNumber;
}
 
/*
 * smgrtruncate() -- Truncate the given forks of supplied relation to
 *                   each specified numbers of blocks
 *
 * The truncation is done immediately, so this can't be rolled back.
 *
 * The caller must hold AccessExclusiveLock on the relation, to ensure that
 * other backends receive the smgr invalidation event that this function sends
 * before they access any forks of the relation again.  The current size of
 * the forks should be provided in old_nblocks.  This function should normally
 * be called in a critical section, but the current size must be checked
 * outside the critical section, and no interrupts or smgr functions relating
 * to this relation should be called in between.
 */
void
smgrtruncate(SMgrRelation reln, ForkNumber *forknum, int nforks,
             BlockNumber *old_nblocks, BlockNumber *nblocks)
{
    int         i;
 
    /*
     * Get rid of any buffers for the about-to-be-deleted blocks. bufmgr will
     * just drop them without bothering to write the contents.
     */
    DropRelationBuffers(reln, forknum, nforks, nblocks);
 
    /*
     * Send a shared-inval message to force other backends to close any smgr
     * references they may have for this rel.  This is useful because they
     * might have open file pointers to segments that got removed, and/or
     * smgr_targblock variables pointing past the new rel end.  (The inval
     * message will come back to our backend, too, causing a
     * probably-unnecessary local smgr flush.  But we don't expect that this
     * is a performance-critical path.)  As in the unlink code, we want to be
     * sure the message is sent before we start changing things on-disk.
     */
    CacheInvalidateSmgr(reln->smgr_rlocator);
 
    /* Do the truncation */
    for (i = 0; i < nforks; i++)
    {
        /* Make the cached size is invalid if we encounter an error. */
        reln->smgr_cached_nblocks[forknum[i]] = InvalidBlockNumber;
 
        smgrsw[reln->smgr_which].smgr_truncate(reln, forknum[i],
                                               old_nblocks[i], nblocks[i]);
 
        /*
         * We might as well update the local smgr_cached_nblocks values. The
         * smgr cache inval message that this function sent will cause other
         * backends to invalidate their copies of smgr_cached_nblocks, and
         * these ones too at the next command boundary. But ensure they aren't
         * outright wrong until then.
         *
         * We can have nblocks > old_nblocks when a relation was truncated
         * multiple times, a replica applied all the truncations, and later
         * restarts from a restartpoint located before the truncations. The
         * relation on disk will be the size of the last truncate. When
         * replaying the first truncate, we will have nblocks > current size.
         * In such cases, smgr_truncate does nothing, so set the cached size
         * to the old size rather than the requested size.
         */
        reln->smgr_cached_nblocks[forknum[i]] =
            nblocks[i] > old_nblocks[i] ? old_nblocks[i] : nblocks[i];
    }
}
 
/*
 * smgrregistersync() -- Request a relation to be sync'd at next checkpoint
 *
 * This can be used after calling smgrwrite() or smgrextend() with skipFsync =
 * true, to register the fsyncs that were skipped earlier.
 *
 * Note: be mindful that a checkpoint could already have happened between the
 * smgrwrite or smgrextend calls and this!  In that case, the checkpoint
 * already missed fsyncing this relation, and you should use smgrimmedsync
 * instead.  Most callers should use the bulk loading facility in bulk_write.c
 * which handles all that.
 */
void
smgrregistersync(SMgrRelation reln, ForkNumber forknum)
{
    HOLD_INTERRUPTS();
    smgrsw[reln->smgr_which].smgr_registersync(reln, forknum);
    RESUME_INTERRUPTS();
}
 
/*
 * smgrimmedsync() -- Force the specified relation to stable storage.
 *
 * Synchronously force all previous writes to the specified relation
 * down to disk.
 *
 * This is useful for building completely new relations (eg, new
 * indexes).  Instead of incrementally WAL-logging the index build
 * steps, we can just write completed index pages to disk with smgrwrite
 * or smgrextend, and then fsync the completed index file before
 * committing the transaction.  (This is sufficient for purposes of
 * crash recovery, since it effectively duplicates forcing a checkpoint
 * for the completed index.  But it is *not* sufficient if one wishes
 * to use the WAL log for PITR or replication purposes: in that case
 * we have to make WAL entries as well.)
 *
 * The preceding writes should specify skipFsync = true to avoid
 * duplicative fsyncs.
 *
 * Note that you need to do FlushRelationBuffers() first if there is
 * any possibility that there are dirty buffers for the relation;
 * otherwise the sync is not very meaningful.
 *
 * Most callers should use the bulk loading facility in bulk_write.c
 * instead of calling this directly.
 */
void
smgrimmedsync(SMgrRelation reln, ForkNumber forknum)
{
    HOLD_INTERRUPTS();
    smgrsw[reln->smgr_which].smgr_immedsync(reln, forknum);
    RESUME_INTERRUPTS();
}
 
/*
 * Return fd for the specified block number and update *off to the appropriate
 * position.
 *
 * This is only to be used for when AIO needs to perform the IO in a different
 * process than where it was issued (e.g. in an IO worker).
 */
static int
smgrfd(SMgrRelation reln, ForkNumber forknum, BlockNumber blocknum, uint32 *off)
{
    int         fd;
 
    /*
     * The caller needs to prevent interrupts from being processed, otherwise
     * the FD could be closed prematurely.
     */
    Assert(!INTERRUPTS_CAN_BE_PROCESSED());
 
    fd = smgrsw[reln->smgr_which].smgr_fd(reln, forknum, blocknum, off);
 
    return fd;
}
 
/*
 * AtEOXact_SMgr
 *
 * This routine is called during transaction commit or abort (it doesn't
 * particularly care which).  All unpinned SMgrRelation objects are destroyed.
 *
 * We do this as a compromise between wanting transient SMgrRelations to
 * live awhile (to amortize the costs of blind writes of multiple blocks)
 * and needing them to not live forever (since we're probably holding open
 * a kernel file descriptor for the underlying file, and we need to ensure
 * that gets closed reasonably soon if the file gets deleted).
 */
void
AtEOXact_SMgr(void)
{
    smgrdestroyall();
}
 
/*
 * This routine is called when we are ordered to release all open files by a
 * ProcSignalBarrier.
 */
bool
ProcessBarrierSmgrRelease(void)
{
    smgrreleaseall();
    return true;
}
 
/*
 * Set target of the IO handle to be smgr and initialize all the relevant
 * pieces of data.
 */
void
pgaio_io_set_target_smgr(PgAioHandle *ioh,
                         SMgrRelationData *smgr,
                         ForkNumber forknum,
                         BlockNumber blocknum,
                         int nblocks,
                         bool skip_fsync)
{
    PgAioTargetData *sd = pgaio_io_get_target_data(ioh);
 
    pgaio_io_set_target(ioh, PGAIO_TID_SMGR);
 
    /* backend is implied via IO owner */
    sd->smgr.rlocator = smgr->smgr_rlocator.locator;
    sd->smgr.forkNum = forknum;
    sd->smgr.blockNum = blocknum;
    sd->smgr.nblocks = nblocks;
    sd->smgr.is_temp = SmgrIsTemp(smgr);
    /* Temp relations should never be fsync'd */
    sd->smgr.skip_fsync = skip_fsync && !SmgrIsTemp(smgr);
}
 
/*
 * Callback for the smgr AIO target, to reopen the file (e.g. because the IO
 * is executed in a worker).
 */
static void
smgr_aio_reopen(PgAioHandle *ioh)
{
    PgAioTargetData *sd = pgaio_io_get_target_data(ioh);
    PgAioOpData *od = pgaio_io_get_op_data(ioh);
    SMgrRelation reln;
    ProcNumber  procno;
    uint32      off;
 
    /*
     * The caller needs to prevent interrupts from being processed, otherwise
     * the FD could be closed again before we get to executing the IO.
     */
    Assert(!INTERRUPTS_CAN_BE_PROCESSED());
 
    if (sd->smgr.is_temp)
        procno = pgaio_io_get_owner(ioh);
    else
        procno = INVALID_PROC_NUMBER;
 
    reln = smgropen(sd->smgr.rlocator, procno);
    switch (pgaio_io_get_op(ioh))
    {
        case PGAIO_OP_INVALID:
            pg_unreachable();
            break;
        case PGAIO_OP_READV:
            od->read.fd = smgrfd(reln, sd->smgr.forkNum, sd->smgr.blockNum, &off);
            Assert(off == od->read.offset);
            break;
        case PGAIO_OP_WRITEV:
            od->write.fd = smgrfd(reln, sd->smgr.forkNum, sd->smgr.blockNum, &off);
            Assert(off == od->write.offset);
            break;
    }
}
 
/*
 * Callback for the smgr AIO target, describing the target of the IO.
 */
static char *
smgr_aio_describe_identity(const PgAioTargetData *sd)
{
    RelPathStr  path;
    char       *desc;
 
    path = relpathbackend(sd->smgr.rlocator,
                          sd->smgr.is_temp ?
                          MyProcNumber : INVALID_PROC_NUMBER,
                          sd->smgr.forkNum);
 
    if (sd->smgr.nblocks == 0)
        desc = psprintf(_("file \"%s\""), path.str);
    else if (sd->smgr.nblocks == 1)
        desc = psprintf(_("block %u in file \"%s\""),
                        sd->smgr.blockNum,
                        path.str);
    else
        desc = psprintf(_("blocks %u..%u in file \"%s\""),
                        sd->smgr.blockNum,
                        sd->smgr.blockNum + sd->smgr.nblocks - 1,
                        path.str);
 
    return desc;
}