aio_types.h

Go to the documentation of this file.

/*-------------------------------------------------------------------------
 *
 * aio_types.h
 *    AIO related types that are useful to include separately, to reduce the
 *    "include burden".
 *
 *
 * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
 * Portions Copyright (c) 1994, Regents of the University of California
 *
 * src/include/storage/aio_types.h
 *
 *-------------------------------------------------------------------------
 */
#ifndef AIO_TYPES_H
#define AIO_TYPES_H
 
#include "storage/block.h"
#include "storage/relfilelocator.h"
 
 
typedef struct PgAioHandle PgAioHandle;
typedef struct PgAioHandleCallbacks PgAioHandleCallbacks;
typedef struct PgAioTargetInfo PgAioTargetInfo;
 
/*
 * A reference to an IO that can be used to wait for the IO (using
 * pgaio_wref_wait()) to complete.
 *
 * These can be passed across process boundaries.
 */
typedef struct PgAioWaitRef
{
    /* internal ID identifying the specific PgAioHandle */
    uint32      aio_index;
 
    /*
     * IO handles are reused. To detect if a handle was reused, and thereby
     * avoid unnecessarily waiting for a newer IO, each time the handle is
     * reused a generation number is increased.
     *
     * To avoid requiring alignment sufficient for an int64, split the
     * generation into two.
     */
    uint32      generation_upper;
    uint32      generation_lower;
} PgAioWaitRef;
 
 
/*
 * Information identifying what the IO is being performed on.
 *
 * This needs sufficient information to
 *
 * a) Reopen the file for the IO if the IO is executed in a context that
 *    cannot use the FD provided initially (e.g. because the IO is executed in
 *    a worker process).
 *
 * b) Describe the object the IO is performed on in log / error messages.
 */
typedef union PgAioTargetData
{
    struct
    {
        RelFileLocator rlocator;    /* physical relation identifier */
        BlockNumber blockNum;   /* blknum relative to begin of reln */
        BlockNumber nblocks;
        ForkNumber  forkNum:8;  /* don't waste 4 byte for four values */
        bool        is_temp:1;  /* proc can be inferred by owning AIO */
        bool        skip_fsync:1;
    }           smgr;
} PgAioTargetData;
 
 
/*
 * The status of an AIO operation.
 */
typedef enum PgAioResultStatus
{
    PGAIO_RS_UNKNOWN,           /* not yet completed / uninitialized */
    PGAIO_RS_OK,
    PGAIO_RS_PARTIAL,           /* did not fully succeed, no warning/error */
    PGAIO_RS_WARNING,           /* [partially] succeeded, with a warning */
    PGAIO_RS_ERROR,             /* failed entirely */
} PgAioResultStatus;
 
 
/*
 * Result of IO operation, visible only to the initiator of IO.
 *
 * We need to be careful about the size of PgAioResult, as it is embedded in
 * every PgAioHandle, as well as every PgAioReturn. Currently we assume we can
 * fit it into one 8 byte value, restricting the space for per-callback error
 * data to PGAIO_RESULT_ERROR_BITS.
 */
#define PGAIO_RESULT_ID_BITS 6
#define PGAIO_RESULT_STATUS_BITS 3
#define PGAIO_RESULT_ERROR_BITS 23
typedef struct PgAioResult
{
    /*
     * This is of type PgAioHandleCallbackID, but can't use a bitfield of an
     * enum, because some compilers treat enums as signed.
     */
    uint32      id:PGAIO_RESULT_ID_BITS;
 
    /* of type PgAioResultStatus, see above */
    uint32      status:PGAIO_RESULT_STATUS_BITS;
 
    /* meaning defined by callback->error */
    uint32      error_data:PGAIO_RESULT_ERROR_BITS;
 
    int32       result;
} PgAioResult;
 
 
StaticAssertDecl(PGAIO_RESULT_ID_BITS +
                 PGAIO_RESULT_STATUS_BITS +
                 PGAIO_RESULT_ERROR_BITS == 32,
                 "PgAioResult bits divided up incorrectly");
StaticAssertDecl(sizeof(PgAioResult) == 8,
                 "PgAioResult has unexpected size");
 
/*
 * Combination of PgAioResult with minimal metadata about the IO.
 *
 * Contains sufficient information to be able, in case the IO [partially]
 * fails, to log/raise an error under control of the IO issuing code.
 */
typedef struct PgAioReturn
{
    PgAioResult result;
    PgAioTargetData target_data;
} PgAioReturn;
 
 
#endif                          /* AIO_TYPES_H */