Line data    Source code

       1             : /*-------------------------------------------------------------------------
       2             :  *
       3             :  * palloc.h
       4             :  *    POSTGRES memory allocator definitions.
       5             :  *
       6             :  * This file contains the basic memory allocation interface that is
       7             :  * needed by almost every backend module.  It is included directly by
       8             :  * postgres.h, so the definitions here are automatically available
       9             :  * everywhere.  Keep it lean!
      10             :  *
      11             :  * Memory allocation occurs within "contexts".  Every chunk obtained from
      12             :  * palloc()/MemoryContextAlloc() is allocated within a specific context.
      13             :  * The entire contents of a context can be freed easily and quickly by
      14             :  * resetting or deleting the context --- this is both faster and less
      15             :  * prone to memory-leakage bugs than releasing chunks individually.
      16             :  * We organize contexts into context trees to allow fine-grain control
      17             :  * over chunk lifetime while preserving the certainty that we will free
      18             :  * everything that should be freed.  See utils/mmgr/README for more info.
      19             :  *
      20             :  *
      21             :  * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
      22             :  * Portions Copyright (c) 1994, Regents of the University of California
      23             :  *
      24             :  * src/include/utils/palloc.h
      25             :  *
      26             :  *-------------------------------------------------------------------------
      27             :  */
      28             : #ifndef PALLOC_H
      29             : #define PALLOC_H
      30             : 
      31             : /*
      32             :  * Type MemoryContextData is declared in nodes/memnodes.h.  Most users
      33             :  * of memory allocation should just treat it as an abstract type, so we
      34             :  * do not provide the struct contents here.
      35             :  */
      36             : typedef struct MemoryContextData *MemoryContext;
      37             : 
      38             : /*
      39             :  * A memory context can have callback functions registered on it.  Any such
      40             :  * function will be called once just before the context is next reset or
      41             :  * deleted.  The MemoryContextCallback struct describing such a callback
      42             :  * typically would be allocated within the context itself, thereby avoiding
      43             :  * any need to manage it explicitly (the reset/delete action will free it).
      44             :  */
      45             : typedef void (*MemoryContextCallbackFunction) (void *arg);
      46             : 
      47             : typedef struct MemoryContextCallback
      48             : {
      49             :     MemoryContextCallbackFunction func; /* function to call */
      50             :     void       *arg;            /* argument to pass it */
      51             :     struct MemoryContextCallback *next; /* next in list of callbacks */
      52             : } MemoryContextCallback;
      53             : 
      54             : /*
      55             :  * CurrentMemoryContext is the default allocation context for palloc().
      56             :  * Avoid accessing it directly!  Instead, use MemoryContextSwitchTo()
      57             :  * to change the setting.
      58             :  */
      59             : extern PGDLLIMPORT MemoryContext CurrentMemoryContext;
      60             : 
      61             : /*
      62             :  * Flags for MemoryContextAllocExtended.
      63             :  */
      64             : #define MCXT_ALLOC_HUGE         0x01    /* allow huge allocation (> 1 GB) */
      65             : #define MCXT_ALLOC_NO_OOM       0x02    /* no failure if out-of-memory */
      66             : #define MCXT_ALLOC_ZERO         0x04    /* zero allocated memory */
      67             : 
      68             : /*
      69             :  * Fundamental memory-allocation operations (more are in utils/memutils.h)
      70             :  */
      71             : extern void *MemoryContextAlloc(MemoryContext context, Size size);
      72             : extern void *MemoryContextAllocZero(MemoryContext context, Size size);
      73             : extern void *MemoryContextAllocExtended(MemoryContext context,
      74             :                                         Size size, int flags);
      75             : extern void *MemoryContextAllocAligned(MemoryContext context,
      76             :                                        Size size, Size alignto, int flags);
      77             : 
      78             : extern void *palloc(Size size);
      79             : extern void *palloc0(Size size);
      80             : extern void *palloc_extended(Size size, int flags);
      81             : extern void *palloc_aligned(Size size, Size alignto, int flags);
      82             : extern pg_nodiscard void *repalloc(void *pointer, Size size);
      83             : extern pg_nodiscard void *repalloc_extended(void *pointer,
      84             :                                             Size size, int flags);
      85             : extern pg_nodiscard void *repalloc0(void *pointer, Size oldsize, Size size);
      86             : extern void pfree(void *pointer);
      87             : 
      88             : /*
      89             :  * Variants with easier notation and more type safety
      90             :  */
      91             : 
      92             : /*
      93             :  * Allocate space for one object of type "type"
      94             :  */
      95             : #define palloc_object(type) ((type *) palloc(sizeof(type)))
      96             : #define palloc0_object(type) ((type *) palloc0(sizeof(type)))
      97             : 
      98             : /*
      99             :  * Allocate space for "count" objects of type "type"
     100             :  */
     101             : #define palloc_array(type, count) ((type *) palloc(sizeof(type) * (count)))
     102             : #define palloc0_array(type, count) ((type *) palloc0(sizeof(type) * (count)))
     103             : 
     104             : /*
     105             :  * Change size of allocation pointed to by "pointer" to have space for "count"
     106             :  * objects of type "type"
     107             :  */
     108             : #define repalloc_array(pointer, type, count) ((type *) repalloc(pointer, sizeof(type) * (count)))
     109             : #define repalloc0_array(pointer, type, oldcount, count) ((type *) repalloc0(pointer, sizeof(type) * (oldcount), sizeof(type) * (count)))
     110             : 
     111             : /* Higher-limit allocators. */
     112             : extern void *MemoryContextAllocHuge(MemoryContext context, Size size);
     113             : extern pg_nodiscard void *repalloc_huge(void *pointer, Size size);
     114             : 
     115             : /*
     116             :  * Although this header file is nominally backend-only, certain frontend
     117             :  * programs like pg_controldata include it via postgres.h.  For some compilers
     118             :  * it's necessary to hide the inline definition of MemoryContextSwitchTo in
     119             :  * this scenario; hence the #ifndef FRONTEND.
     120             :  */
     121             : 
     122             : #ifndef FRONTEND
     123             : static inline MemoryContext
     124   856271634 : MemoryContextSwitchTo(MemoryContext context)
     125             : {
     126   856271634 :     MemoryContext old = CurrentMemoryContext;
     127             : 
     128   856271634 :     CurrentMemoryContext = context;
     129   856271634 :     return old;
     130             : }
     131             : #endif                          /* FRONTEND */
     132             : 
     133             : /* Registration of memory context reset/delete callbacks */
     134             : extern void MemoryContextRegisterResetCallback(MemoryContext context,
     135             :                                                MemoryContextCallback *cb);
     136             : 
     137             : /*
     138             :  * These are like standard strdup() except the copied string is
     139             :  * allocated in a context, not with malloc().
     140             :  */
     141             : extern char *MemoryContextStrdup(MemoryContext context, const char *string);
     142             : extern char *pstrdup(const char *in);
     143             : extern char *pnstrdup(const char *in, Size len);
     144             : 
     145             : extern char *pchomp(const char *in);
     146             : 
     147             : /* sprintf into a palloc'd buffer --- these are in psprintf.c */
     148             : extern char *psprintf(const char *fmt,...) pg_attribute_printf(1, 2);
     149             : extern size_t pvsnprintf(char *buf, size_t len, const char *fmt, va_list args) pg_attribute_printf(3, 0);
     150             : 
     151             : #endif                          /* PALLOC_H */