mcxtfuncs.c

Go to the documentation of this file.

/*-------------------------------------------------------------------------
 *
 * mcxtfuncs.c
 *    Functions to show backend memory context.
 *
 * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
 * Portions Copyright (c) 1994, Regents of the University of California
 *
 *
 * IDENTIFICATION
 *    src/backend/utils/adt/mcxtfuncs.c
 *
 *-------------------------------------------------------------------------
 */
 
#include "postgres.h"
 
#include "funcapi.h"
#include "mb/pg_wchar.h"
#include "miscadmin.h"
#include "access/twophase.h"
#include "catalog/pg_authid_d.h"
#include "storage/proc.h"
#include "storage/procarray.h"
#include "utils/acl.h"
#include "utils/array.h"
#include "utils/builtins.h"
#include "utils/hsearch.h"
#include "utils/memutils.h"
#include "utils/wait_event_types.h"
 
/* ----------
 * The max bytes for showing identifiers of MemoryContext.
 * ----------
 */
#define MEMORY_CONTEXT_IDENT_DISPLAY_SIZE   1024
struct MemoryStatsBackendState *memCxtState = NULL;
struct MemoryStatsCtl *memCxtArea = NULL;
 
/*
 * int_list_to_array
 *      Convert an IntList to an array of INT4OIDs.
 */
static Datum
int_list_to_array(const List *list)
{
    Datum      *datum_array;
    int         length;
    ArrayType  *result_array;
 
    length = list_length(list);
    datum_array = (Datum *) palloc(length * sizeof(Datum));
 
    foreach_int(i, list)
        datum_array[foreach_current_index(i)] = Int32GetDatum(i);
 
    result_array = construct_array_builtin(datum_array, length, INT4OID);
 
    return PointerGetDatum(result_array);
}
 
/*
 * PutMemoryContextsStatsTupleStore
 *      Add details for the given MemoryContext to 'tupstore'.
 */
static void
PutMemoryContextsStatsTupleStore(Tuplestorestate *tupstore,
                                 TupleDesc tupdesc, MemoryContext context,
                                 HTAB *context_id_lookup)
{
#define PG_GET_BACKEND_MEMORY_CONTEXTS_COLS 10
 
    Datum       values[PG_GET_BACKEND_MEMORY_CONTEXTS_COLS];
    bool        nulls[PG_GET_BACKEND_MEMORY_CONTEXTS_COLS];
    MemoryContextCounters stat;
    List       *path = NIL;
    const char *name;
    const char *ident;
    const char *type;
 
    Assert(MemoryContextIsValid(context));
 
    /*
     * Figure out the transient context_id of this context and each of its
     * ancestors.
     */
    for (MemoryContext cur = context; cur != NULL; cur = cur->parent)
    {
        MemoryStatsContextId *entry;
        bool        found;
 
        entry = hash_search(context_id_lookup, &cur, HASH_FIND, &found);
 
        if (!found)
            elog(ERROR, "hash table corrupted");
        path = lcons_int(entry->context_id, path);
    }
 
    /* Examine the context itself */
    memset(&stat, 0, sizeof(stat));
    (*context->methods->stats) (context, NULL, NULL, &stat, true);
 
    memset(values, 0, sizeof(values));
    memset(nulls, 0, sizeof(nulls));
 
    name = context->name;
    ident = context->ident;
 
    /*
     * To be consistent with logging output, we label dynahash contexts with
     * just the hash table name as with MemoryContextStatsPrint().
     */
    if (ident && strcmp(name, "dynahash") == 0)
    {
        name = ident;
        ident = NULL;
    }
 
    if (name)
        values[0] = CStringGetTextDatum(name);
    else
        nulls[0] = true;
 
    if (ident)
    {
        int         idlen = strlen(ident);
        char        clipped_ident[MEMORY_CONTEXT_IDENT_DISPLAY_SIZE];
 
        /*
         * Some identifiers such as SQL query string can be very long,
         * truncate oversize identifiers.
         */
        if (idlen >= MEMORY_CONTEXT_IDENT_DISPLAY_SIZE)
            idlen = pg_mbcliplen(ident, idlen, MEMORY_CONTEXT_IDENT_DISPLAY_SIZE - 1);
 
        memcpy(clipped_ident, ident, idlen);
        clipped_ident[idlen] = '\0';
        values[1] = CStringGetTextDatum(clipped_ident);
    }
    else
        nulls[1] = true;
 
    type = ContextTypeToString(context->type);
 
    values[2] = CStringGetTextDatum(type);
    values[3] = Int32GetDatum(list_length(path));   /* level */
    values[4] = int_list_to_array(path);
    values[5] = Int64GetDatum(stat.totalspace);
    values[6] = Int64GetDatum(stat.nblocks);
    values[7] = Int64GetDatum(stat.freespace);
    values[8] = Int64GetDatum(stat.freechunks);
    values[9] = Int64GetDatum(stat.totalspace - stat.freespace);
 
    tuplestore_putvalues(tupstore, tupdesc, values, nulls);
    list_free(path);
}
 
/*
 * ContextTypeToString
 *      Returns a textual representation of a context type
 *
 * This should cover the same types as MemoryContextIsValid.
 */
const char *
ContextTypeToString(NodeTag type)
{
    const char *context_type;
 
    switch (type)
    {
        case T_AllocSetContext:
            context_type = "AllocSet";
            break;
        case T_GenerationContext:
            context_type = "Generation";
            break;
        case T_SlabContext:
            context_type = "Slab";
            break;
        case T_BumpContext:
            context_type = "Bump";
            break;
        default:
            context_type = "???";
            break;
    }
    return context_type;
}
 
/*
 * pg_get_backend_memory_contexts
 *      SQL SRF showing backend memory context.
 */
Datum
pg_get_backend_memory_contexts(PG_FUNCTION_ARGS)
{
    ReturnSetInfo *rsinfo = (ReturnSetInfo *) fcinfo->resultinfo;
    int         context_id;
    List       *contexts;
    HASHCTL     ctl;
    HTAB       *context_id_lookup;
 
    ctl.keysize = sizeof(MemoryContext);
    ctl.entrysize = sizeof(MemoryStatsContextId);
    ctl.hcxt = CurrentMemoryContext;
 
    context_id_lookup = hash_create("pg_get_backend_memory_contexts",
                                    256,
                                    &ctl,
                                    HASH_ELEM | HASH_BLOBS | HASH_CONTEXT);
 
    InitMaterializedSRF(fcinfo, 0);
 
    /*
     * Here we use a non-recursive algorithm to visit all MemoryContexts
     * starting with TopMemoryContext.  The reason we avoid using a recursive
     * algorithm is because we want to assign the context_id breadth-first.
     * I.e. all contexts at level 1 are assigned IDs before contexts at level
     * 2.  Because contexts closer to TopMemoryContext are less likely to
     * change, this makes the assigned context_id more stable.  Otherwise, if
     * the first child of TopMemoryContext obtained an additional grandchild,
     * the context_id for the second child of TopMemoryContext would change.
     */
    contexts = list_make1(TopMemoryContext);
 
    /* TopMemoryContext will always have a context_id of 1 */
    context_id = 1;
 
    foreach_ptr(MemoryContextData, cur, contexts)
    {
        MemoryStatsContextId *entry;
        bool        found;
 
        /*
         * Record the context_id that we've assigned to each MemoryContext.
         * PutMemoryContextsStatsTupleStore needs this to populate the "path"
         * column with the parent context_ids.
         */
        entry = (MemoryStatsContextId *) hash_search(context_id_lookup, &cur,
                                                     HASH_ENTER, &found);
        entry->context_id = context_id++;
        Assert(!found);
 
        PutMemoryContextsStatsTupleStore(rsinfo->setResult,
                                         rsinfo->setDesc,
                                         cur,
                                         context_id_lookup);
 
        /*
         * Append all children onto the contexts list so they're processed by
         * subsequent iterations.
         */
        for (MemoryContext c = cur->firstchild; c != NULL; c = c->nextchild)
            contexts = lappend(contexts, c);
    }
 
    hash_destroy(context_id_lookup);
 
    return (Datum) 0;
}
 
/*
 * pg_log_backend_memory_contexts
 *      Signal a backend or an auxiliary process to log its memory contexts.
 *
 * By default, only superusers are allowed to signal to log the memory
 * contexts because allowing any users to issue this request at an unbounded
 * rate would cause lots of log messages and which can lead to denial of
 * service. Additional roles can be permitted with GRANT.
 *
 * On receipt of this signal, a backend or an auxiliary process sets the flag
 * in the signal handler, which causes the next CHECK_FOR_INTERRUPTS()
 * or process-specific interrupt handler to log the memory contexts.
 */
Datum
pg_log_backend_memory_contexts(PG_FUNCTION_ARGS)
{
    int         pid = PG_GETARG_INT32(0);
    PGPROC     *proc;
    ProcNumber  procNumber = INVALID_PROC_NUMBER;
 
    /*
     * See if the process with given pid is a backend or an auxiliary process.
     */
    proc = BackendPidGetProc(pid);
    if (proc == NULL)
        proc = AuxiliaryPidGetProc(pid);
 
    /*
     * BackendPidGetProc() and AuxiliaryPidGetProc() return NULL if the pid
     * isn't valid; but by the time we reach kill(), a process for which we
     * get a valid proc here might have terminated on its own.  There's no way
     * to acquire a lock on an arbitrary process to prevent that. But since
     * this mechanism is usually used to debug a backend or an auxiliary
     * process running and consuming lots of memory, that it might end on its
     * own first and its memory contexts are not logged is not a problem.
     */
    if (proc == NULL)
    {
        /*
         * This is just a warning so a loop-through-resultset will not abort
         * if one backend terminated on its own during the run.
         */
        ereport(WARNING,
                (errmsg("PID %d is not a PostgreSQL server process", pid)));
        PG_RETURN_BOOL(false);
    }
 
    procNumber = GetNumberFromPGProc(proc);
    if (SendProcSignal(pid, PROCSIG_LOG_MEMORY_CONTEXT, procNumber) < 0)
    {
        /* Again, just a warning to allow loops */
        ereport(WARNING,
                (errmsg("could not send signal to process %d: %m", pid)));
        PG_RETURN_BOOL(false);
    }
 
    PG_RETURN_BOOL(true);
}
 
/*
 * pg_get_process_memory_contexts
 *      Signal a backend or an auxiliary process to send its memory contexts,
 *      wait for the results and display them.
 *
 * By default, only superusers or users with ROLE_PG_READ_ALL_STATS are allowed
 * to signal a process to return the memory contexts. This is because allowing
 * any users to issue this request at an unbounded rate would cause lots of
 * requests to be sent, which can lead to denial of service. Additional roles
 * can be permitted with GRANT.
 *
 * On receipt of this signal, a backend or an auxiliary process sets the flag
 * in the signal handler, which causes the next CHECK_FOR_INTERRUPTS()
 * or process-specific interrupt handler to copy the memory context details
 * to a dynamic shared memory space.
 *
 * We have defined a limit on DSA memory that could be allocated per process -
 * if the process has more memory contexts than what can fit in the allocated
 * size, the excess contexts are summarized and represented as cumulative total
 * at the end of the buffer.
 *
 * After sending the signal, wait on a condition variable. The publishing
 * backend, after copying the data to shared memory, sends signal on that
 * condition variable. There is one condition variable per publishing backend.
 * Once the condition variable is signalled, check if the latest memory context
 * information is available and display.
 *
 * If the publishing backend does not respond before the condition variable
 * times out, which is set to MEMSTATS_WAIT_TIMEOUT, retry given that there is
 * time left within the timeout specified by the user, before giving up and
 * returning previously published statistics, if any. If no previous statistics
 * exist, return NULL.
 */
#define MEMSTATS_WAIT_TIMEOUT 100
Datum
pg_get_process_memory_contexts(PG_FUNCTION_ARGS)
{
    int         pid = PG_GETARG_INT32(0);
    bool        summary = PG_GETARG_BOOL(1);
    double      timeout = PG_GETARG_FLOAT8(2);
    PGPROC     *proc;
    ProcNumber  procNumber = INVALID_PROC_NUMBER;
    bool        proc_is_aux = false;
    ReturnSetInfo *rsinfo = (ReturnSetInfo *) fcinfo->resultinfo;
    MemoryStatsEntry *memcxt_info;
    TimestampTz start_timestamp;
 
    /*
     * See if the process with given pid is a backend or an auxiliary process
     * and remember the type for when we requery the process later.
     */
    proc = BackendPidGetProc(pid);
    if (proc == NULL)
    {
        proc = AuxiliaryPidGetProc(pid);
        proc_is_aux = true;
    }
 
    /*
     * BackendPidGetProc() and AuxiliaryPidGetProc() return NULL if the pid
     * isn't valid; this is however not a problem and leave with a WARNING.
     * See comment in pg_log_backend_memory_contexts for a discussion on this.
     */
    if (proc == NULL)
    {
        /*
         * This is just a warning so a loop-through-resultset will not abort
         * if one backend terminated on its own during the run.
         */
        ereport(WARNING,
                errmsg("PID %d is not a PostgreSQL server process", pid));
        PG_RETURN_NULL();
    }
 
    InitMaterializedSRF(fcinfo, 0);
 
    procNumber = GetNumberFromPGProc(proc);
 
    LWLockAcquire(&memCxtState[procNumber].lw_lock, LW_EXCLUSIVE);
    memCxtState[procNumber].summary = summary;
    LWLockRelease(&memCxtState[procNumber].lw_lock);
 
    start_timestamp = GetCurrentTimestamp();
 
    /*
     * Send a signal to a PostgreSQL process, informing it we want it to
     * produce information about its memory contexts.
     */
    if (SendProcSignal(pid, PROCSIG_GET_MEMORY_CONTEXT, procNumber) < 0)
    {
        ereport(WARNING,
                errmsg("could not send signal to process %d: %m", pid));
        PG_RETURN_NULL();
    }
 
    /*
     * Even if the proc has published statistics, the may not be due to the
     * current request, but previously published stats.  Check if the stats
     * are updated by comparing the timestamp, if the stats are newer than our
     * previously recorded timestamp from before sending the procsignal, they
     * must by definition be updated. Wait for the timeout specified by the
     * user, following which display old statistics if available or return
     * NULL.
     */
    while (1)
    {
        long        msecs;
 
        /*
         * We expect to come out of sleep when the requested process has
         * finished publishing the statistics, verified using the valid DSA
         * pointer.
         *
         * Make sure that the information belongs to pid we requested
         * information for, Otherwise loop back and wait for the server
         * process to finish publishing statistics.
         */
        LWLockAcquire(&memCxtState[procNumber].lw_lock, LW_EXCLUSIVE);
 
        /*
         * Note in procnumber.h file says that a procNumber can be re-used for
         * a different backend immediately after a backend exits. In case an
         * old process' data was there and not updated by the current process
         * in the slot identified by the procNumber, the pid of the requested
         * process and the proc_id might not match.
         */
        if (memCxtState[procNumber].proc_id == pid)
        {
            /*
             * Break if the latest stats have been read, indicated by
             * statistics timestamp being newer than the current request
             * timestamp.
             */
            msecs = TimestampDifferenceMilliseconds(start_timestamp,
                                                    memCxtState[procNumber].stats_timestamp);
 
            if (DsaPointerIsValid(memCxtState[procNumber].memstats_dsa_pointer)
                && msecs > 0)
                break;
        }
        LWLockRelease(&memCxtState[procNumber].lw_lock);
 
        /*
         * Recheck the state of the backend before sleeping on the condition
         * variable to ensure the process is still alive.  Only check the
         * relevant process type based on the earlier PID check.
         */
        if (proc_is_aux)
            proc = AuxiliaryPidGetProc(pid);
        else
            proc = BackendPidGetProc(pid);
 
        /*
         * The process ending during memory context processing is not an
         * error.
         */
        if (proc == NULL)
        {
            ereport(WARNING,
                    errmsg("PID %d is no longer a PostgreSQL server process",
                           pid));
            PG_RETURN_NULL();
        }
 
        msecs = TimestampDifferenceMilliseconds(start_timestamp, GetCurrentTimestamp());
 
        /*
         * If we haven't already exceeded the timeout value, sleep for the
         * remainder of the timeout on the condition variable.
         */
        if (msecs > 0 && msecs < (timeout * 1000))
        {
            /*
             * Wait for the timeout as defined by the user. If no updated
             * statistics are available within the allowed time then display
             * previously published statistics if there are any. If no
             * previous statistics are available then return NULL.  The timer
             * is defined in milliseconds since that's what the condition
             * variable sleep uses.
             */
            if (ConditionVariableTimedSleep(&memCxtState[procNumber].memcxt_cv,
                                            ((timeout * 1000) - msecs), WAIT_EVENT_MEM_CXT_PUBLISH))
            {
                LWLockAcquire(&memCxtState[procNumber].lw_lock, LW_EXCLUSIVE);
                /* Displaying previously published statistics if available */
                if (DsaPointerIsValid(memCxtState[procNumber].memstats_dsa_pointer))
                    break;
                else
                {
                    LWLockRelease(&memCxtState[procNumber].lw_lock);
                    PG_RETURN_NULL();
                }
            }
        }
        else
        {
            LWLockAcquire(&memCxtState[procNumber].lw_lock, LW_EXCLUSIVE);
            /* Displaying previously published statistics if available */
            if (DsaPointerIsValid(memCxtState[procNumber].memstats_dsa_pointer))
                break;
            else
            {
                LWLockRelease(&memCxtState[procNumber].lw_lock);
                PG_RETURN_NULL();
            }
        }
    }
 
    /*
     * We should only reach here with a valid DSA handle, either containing
     * updated statistics or previously published statistics (identified by
     * the timestamp.
     */
    Assert(memCxtArea->memstats_dsa_handle != DSA_HANDLE_INVALID);
    /* Attach to the dsa area if we have not already done so */
    if (MemoryStatsDsaArea == NULL)
    {
        MemoryContext oldcontext = CurrentMemoryContext;
 
        MemoryContextSwitchTo(TopMemoryContext);
        MemoryStatsDsaArea = dsa_attach(memCxtArea->memstats_dsa_handle);
        MemoryContextSwitchTo(oldcontext);
        dsa_pin_mapping(MemoryStatsDsaArea);
    }
 
    /*
     * Backend has finished publishing the stats, project them.
     */
    memcxt_info = (MemoryStatsEntry *)
        dsa_get_address(MemoryStatsDsaArea, memCxtState[procNumber].memstats_dsa_pointer);
 
#define PG_GET_PROCESS_MEMORY_CONTEXTS_COLS 12
    for (int i = 0; i < memCxtState[procNumber].total_stats; i++)
    {
        ArrayType  *path_array;
        int         path_length;
        Datum       values[PG_GET_PROCESS_MEMORY_CONTEXTS_COLS];
        bool        nulls[PG_GET_PROCESS_MEMORY_CONTEXTS_COLS];
        char       *name;
        char       *ident;
        Datum      *path_datum = NULL;
        int        *path_int = NULL;
 
        memset(values, 0, sizeof(values));
        memset(nulls, 0, sizeof(nulls));
 
        if (DsaPointerIsValid(memcxt_info[i].name))
        {
            name = (char *) dsa_get_address(MemoryStatsDsaArea, memcxt_info[i].name);
            values[0] = CStringGetTextDatum(name);
        }
        else
            nulls[0] = true;
 
        if (DsaPointerIsValid(memcxt_info[i].ident))
        {
            ident = (char *) dsa_get_address(MemoryStatsDsaArea, memcxt_info[i].ident);
            values[1] = CStringGetTextDatum(ident);
        }
        else
            nulls[1] = true;
 
        values[2] = CStringGetTextDatum(ContextTypeToString(memcxt_info[i].type));
 
        path_length = memcxt_info[i].path_length;
        path_datum = (Datum *) palloc(path_length * sizeof(Datum));
        if (DsaPointerIsValid(memcxt_info[i].path))
        {
            path_int = (int *) dsa_get_address(MemoryStatsDsaArea, memcxt_info[i].path);
            for (int j = 0; j < path_length; j++)
                path_datum[j] = Int32GetDatum(path_int[j]);
            path_array = construct_array_builtin(path_datum, path_length, INT4OID);
            values[3] = PointerGetDatum(path_array);
        }
        else
            nulls[3] = true;
 
        values[4] = Int32GetDatum(memcxt_info[i].levels);
        values[5] = Int64GetDatum(memcxt_info[i].totalspace);
        values[6] = Int64GetDatum(memcxt_info[i].nblocks);
        values[7] = Int64GetDatum(memcxt_info[i].freespace);
        values[8] = Int64GetDatum(memcxt_info[i].freechunks);
        values[9] = Int64GetDatum(memcxt_info[i].totalspace -
                                  memcxt_info[i].freespace);
        values[10] = Int32GetDatum(memcxt_info[i].num_agg_stats);
        values[11] = TimestampTzGetDatum(memCxtState[procNumber].stats_timestamp);
 
        tuplestore_putvalues(rsinfo->setResult, rsinfo->setDesc,
                             values, nulls);
    }
    LWLockRelease(&memCxtState[procNumber].lw_lock);
 
    ConditionVariableCancelSleep();
 
    PG_RETURN_NULL();
}
 
Size
MemoryContextReportingShmemSize(void)
{
    Size        sz = 0;
    Size        TotalProcs = 0;
 
    TotalProcs = add_size(TotalProcs, NUM_AUXILIARY_PROCS);
    TotalProcs = add_size(TotalProcs, MaxBackends);
    sz = add_size(sz, mul_size(TotalProcs, sizeof(MemoryStatsBackendState)));
 
    sz = add_size(sz, sizeof(MemoryStatsCtl));
 
    return sz;
}
 
/*
 * Initialize shared memory for displaying memory context statistics
 */
void
MemoryContextReportingShmemInit(void)
{
    bool        found;
 
    memCxtArea = (MemoryStatsCtl *)
        ShmemInitStruct("MemoryStatsCtl",
                        sizeof(MemoryStatsCtl), &found);
 
    if (!found)
    {
        LWLockInitialize(&memCxtArea->lw_lock, LWTRANCHE_MEMORY_CONTEXT_REPORTING_STATE);
        memCxtArea->memstats_dsa_handle = DSA_HANDLE_INVALID;
    }
 
    memCxtState = (MemoryStatsBackendState *)
        ShmemInitStruct("MemoryStatsBackendState",
                        ((MaxBackends + NUM_AUXILIARY_PROCS) * sizeof(MemoryStatsBackendState)),
                        &found);
 
    if (found)
        return;
 
    for (int i = 0; i < (MaxBackends + NUM_AUXILIARY_PROCS); i++)
    {
        ConditionVariableInit(&memCxtState[i].memcxt_cv);
        LWLockInitialize(&memCxtState[i].lw_lock, LWTRANCHE_MEMORY_CONTEXT_REPORTING_PROC);
        memCxtState[i].memstats_dsa_pointer = InvalidDsaPointer;
    }
}