/*-------------------------------------------------------------------------

 *

 * pmchild.c

 *    Functions for keeping track of postmaster child processes.

 *

 * Postmaster keeps track of all child processes so that when a process exits,

 * it knows what kind of a process it was and can clean up accordingly.  Every

 * child process is allocated a PMChild struct from a fixed pool of structs.

 * The size of the pool is determined by various settings that configure how

 * many worker processes and backend connections are allowed, i.e.

 * autovacuum_worker_slots, max_worker_processes, max_wal_senders, and

 * max_connections.

 *

 * Dead-end backends are handled slightly differently.  There is no limit

 * on the number of dead-end backends, and they do not need unique IDs, so

 * their PMChild structs are allocated dynamically, not from a pool.

 *

 * The structures and functions in this file are private to the postmaster

 * process.  But note that there is an array in shared memory, managed by

 * pmsignal.c, that mirrors this.

 *

 *

 * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group

 * Portions Copyright (c) 1994, Regents of the University of California

 *

 * IDENTIFICATION

 *    src/backend/postmaster/pmchild.c

 *

 *-------------------------------------------------------------------------

 */

#include "postgres.h"

#include "miscadmin.h"

#include "postmaster/autovacuum.h"

#include "postmaster/postmaster.h"

#include "replication/walsender.h"

#include "storage/pmsignal.h"

#include "storage/proc.h"

/*

 * Freelists for different kinds of child processes.  We maintain separate

 * pools for each, so that for example launching a lot of regular backends

 * cannot prevent autovacuum or an aux process from launching.

 */

typedef struct PMChildPool

{

  int     size;     /* number of PMChild slots reserved for this

                 * kind of processes */

  int     first_slotno; /* first slot belonging to this pool */

  dlist_head  freelist;   /* currently unused PMChild entries */

} PMChildPool;

static PMChildPool pmchild_pools[BACKEND_NUM_TYPES];

NON_EXEC_STATIC int num_pmchild_slots = 0;

/*

 * List of active child processes.  This includes dead-end children.

 */

dlist_head  ActiveChildList;

/*

 * MaxLivePostmasterChildren

 *

 * This reports the number of postmaster child processes that can be active.

 * It includes all children except for dead-end children.  This allows the

 * array in shared memory (PMChildFlags) to have a fixed maximum size.

 */

int

MaxLivePostmasterChildren(void)

{

  if (num_pmchild_slots == 0)

    elog(ERROR, "PM child array not initialized yet");

  return num_pmchild_slots;

}

/*

 * Initialize at postmaster startup

 *

 * Note: This is not called on crash restart.  We rely on PMChild entries to

 * remain valid through the restart process.  This is important because the

 * syslogger survives through the crash restart process, so we must not

 * invalidate its PMChild slot.

 */

void

InitPostmasterChildSlots(void)

{

  int     slotno;

  PMChild    *slots;

  /*

   * We allow more connections here than we can have backends because some

   * might still be authenticating; they might fail auth, or some existing

   * backend might exit before the auth cycle is completed.  The exact

   * MaxConnections limit is enforced when a new backend tries to join the

   * PGPROC array.

   *

   * WAL senders start out as regular backends, so they share the same pool.

   */

  pmchild_pools[B_BACKEND].size = 2 * (MaxConnections + max_wal_senders);

  pmchild_pools[B_AUTOVAC_WORKER].size = autovacuum_worker_slots;

  pmchild_pools[B_BG_WORKER].size = max_worker_processes;

  pmchild_pools[B_IO_WORKER].size = MAX_IO_WORKERS;

  /*

   * There can be only one of each of these running at a time.  They each

   * get their own pool of just one entry.

   */

  pmchild_pools[B_AUTOVAC_LAUNCHER].size = 1;

  pmchild_pools[B_SLOTSYNC_WORKER].size = 1;

  pmchild_pools[B_ARCHIVER].size = 1;

  pmchild_pools[B_BG_WRITER].size = 1;

  pmchild_pools[B_CHECKPOINTER].size = 1;

  pmchild_pools[B_STARTUP].size = 1;

  pmchild_pools[B_WAL_RECEIVER].size = 1;

  pmchild_pools[B_WAL_SUMMARIZER].size = 1;

  pmchild_pools[B_WAL_WRITER].size = 1;

  pmchild_pools[B_LOGGER].size = 1;

  /* The rest of the pmchild_pools are left at zero size */

  /* Count the total number of slots */

  num_pmchild_slots = 0;

  for (int i = 0; i < BACKEND_NUM_TYPES; i++)

    num_pmchild_slots += pmchild_pools[i].size;

  /* Initialize them */

  slots = palloc(num_pmchild_slots * sizeof(PMChild));

  slotno = 0;

  for (int btype = 0; btype < BACKEND_NUM_TYPES; btype++)

  {

    pmchild_pools[btype].first_slotno = slotno + 1;

    dlist_init(&pmchild_pools[btype].freelist);

    for (int j = 0; j < pmchild_pools[btype].size; j++)

    {

      slots[slotno].pid = 0;

      slots[slotno].child_slot = slotno + 1;

      slots[slotno].bkend_type = B_INVALID;

      slots[slotno].rw = NULL;

      slots[slotno].bgworker_notify = false;

      dlist_push_tail(&pmchild_pools[btype].freelist, &slots[slotno].elem);

      slotno++;

    }

  }

  Assert(slotno == num_pmchild_slots);

  /* Initialize other structures */

  dlist_init(&ActiveChildList);

}

/*

 * Allocate a PMChild entry for a postmaster child process of given type.

 *

 * The entry is taken from the right pool for the type.

 *

 * pmchild->child_slot in the returned struct is unique among all active child

 * processes.

 */

PMChild *

AssignPostmasterChildSlot(BackendType btype)

{

  dlist_head *freelist;

  PMChild    *pmchild;

  if (pmchild_pools[btype].size == 0)

    elog(ERROR, "cannot allocate a PMChild slot for backend type %d", btype);

  freelist = &pmchild_pools[btype].freelist;

  if (dlist_is_empty(freelist))

    return NULL;

  pmchild = dlist_container(PMChild, elem, dlist_pop_head_node(freelist));

  pmchild->pid = 0;

  pmchild->bkend_type = btype;

  pmchild->rw = NULL;

  pmchild->bgworker_notify = true;

  /*

   * pmchild->child_slot for each entry was initialized when the array of

   * slots was allocated.  Sanity check it.

   */

  if (!(pmchild->child_slot >= pmchild_pools[btype].first_slotno &&

      pmchild->child_slot < pmchild_pools[btype].first_slotno + pmchild_pools[btype].size))

  {

    elog(ERROR, "pmchild freelist for backend type %d is corrupt",

       pmchild->bkend_type);

  }

  dlist_push_head(&ActiveChildList, &pmchild->elem);

  /* Update the status in the shared memory array */

  MarkPostmasterChildSlotAssigned(pmchild->child_slot);

  elog(DEBUG2, "assigned pm child slot %d for %s",

     pmchild->child_slot, PostmasterChildName(btype));

  return pmchild;

}

/*

 * Allocate a PMChild struct for a dead-end backend.  Dead-end children are

 * not assigned a child_slot number.  The struct is palloc'd; returns NULL if

 * out of memory.

 */

PMChild *

AllocDeadEndChild(void)

{

  PMChild    *pmchild;

  elog(DEBUG2, "allocating dead-end child");

  pmchild = (PMChild *) palloc_extended(sizeof(PMChild), MCXT_ALLOC_NO_OOM);

  if (pmchild)

  {

    pmchild->pid = 0;

    pmchild->child_slot = 0;

    pmchild->bkend_type = B_DEAD_END_BACKEND;

    pmchild->rw = NULL;

    pmchild->bgworker_notify = false;

    dlist_push_head(&ActiveChildList, &pmchild->elem);

  }

  return pmchild;

}

/*

 * Release a PMChild slot, after the child process has exited.

 *

 * Returns true if the child detached cleanly from shared memory, false

 * otherwise (see MarkPostmasterChildSlotUnassigned).

 */

bool

ReleasePostmasterChildSlot(PMChild *pmchild)

{

  dlist_delete(&pmchild->elem);

  if (pmchild->bkend_type == B_DEAD_END_BACKEND)

  {

    elog(DEBUG2, "releasing dead-end backend");

    pfree(pmchild);

    return true;

  }

  else

  {

    PMChildPool *pool;

    elog(DEBUG2, "releasing pm child slot %d", pmchild->child_slot);

    /* WAL senders start out as regular backends, and share the pool */

    if (pmchild->bkend_type == B_WAL_SENDER)

      pool = &pmchild_pools[B_BACKEND];

    else

      pool = &pmchild_pools[pmchild->bkend_type];

    /* sanity check that we return the entry to the right pool */

    if (!(pmchild->child_slot >= pool->first_slotno &&

        pmchild->child_slot < pool->first_slotno + pool->size))

    {

      elog(ERROR, "pmchild freelist for backend type %d is corrupt",

         pmchild->bkend_type);

    }

    dlist_push_head(&pool->freelist, &pmchild->elem);

    return MarkPostmasterChildSlotUnassigned(pmchild->child_slot);

  }

}

/*

 * Find the PMChild entry of a running child process by PID.

 */

PMChild *

FindPostmasterChildByPid(int pid)

{

  dlist_iter  iter;

  dlist_foreach(iter, &ActiveChildList)

  {

    PMChild    *bp = dlist_container(PMChild, elem, iter.cur);

    if (bp->pid == pid)

      return bp;

  }

  return NULL;

}