Struct pgx::pgbox::PgBox

#[repr(transparent)]
pub struct PgBox<T, AllocatedBy: WhoAllocated<T> = AllocatedByPostgres> { /* private fields */ }

Similar to Rust’s Box<T> type, PgBox<T> also represents heap-allocated memory.

However, it represents a heap-allocated pointer that was allocated by Postgres’s memory allocation functions (palloc, etc). Think of PgBox<T> as a wrapper around an otherwise opaque Postgres type that is projected as a concrete Rust type.

Depending on its usage, it’ll interoperate correctly with Rust’s Drop semantics, such that the backing Postgres-allocated memory is pfree()'d when the PgBox<T> is dropped, but it is possible to effectively return management of the memory back to Postgres (to free on Transaction end, for example) by calling ::into_pg() or ``::into_pg_boxed()`. This is especially useful for returning values back to Postgres.

Examples

This example allocates a simple Postgres structure, modifies it, and returns it back to Postgres:

use pgx::*;

#[pg_guard]
pub fn do_something() -> pg_sys::ItemPointer {
    // postgres-allocate an ItemPointerData structure
    let mut tid = PgBox::<pg_sys::ItemPointerData>::alloc();

    // set its position to 42
    tid.ip_posid = 42;

    // return it to Postgres
    tid.into_pg()
}

A similar example, but instead the PgBox<T>’s backing memory gets freed when the box is dropped:

use pgx::*;

#[pg_guard]
pub fn do_something()  {
    // postgres-allocate an ItemPointerData structure
    let mut tid = PgBox::<pg_sys::ItemPointerData>::alloc();

    // set its position to 42
    tid.ip_posid = 42;

    // tid gets dropped here and as such, gets immediately pfree()'d
}

Alternatively, perhaps you want to work with a pointer Postgres gave you as if it were a Rust type, but it can’t be freed on Drop since you don’t own it – Postgres does:

use pgx::*;

#[pg_guard]
pub fn do_something()  {
    // open a relation and project it as a pg_sys::Relation
    let relid: pg_sys::Oid = 42;
    let lockmode = pg_sys::AccessShareLock as i32;
    let relation = unsafe { PgBox::from_pg(pg_sys::relation_open(relid, lockmode)) };

    // do something with/to 'relation'
    // ...

    // pass the relation back to Postgres
    unsafe { pg_sys::relation_close(relation.as_ptr(), lockmode); }

    // While the `PgBox` instance gets dropped, the backing Postgres-allocated pointer is
    // **not** freed since it came "::from_pg()".  We don't own the underlying memory so
    // we can't free it
}

Implementations

impl<T> PgBox<T, AllocatedByPostgres>

pub unsafe fn from_pg(ptr: *mut T) -> PgBox<T, AllocatedByPostgres>

Box a pointer that cames from Postgres.

When this PgBox<T> is dropped, the boxed memory is not freed. Since Postgres allocated it, Postgres is responsible for freeing it.

impl<T> PgBox<T, AllocatedByRust>

pub fn new(val: T) -> PgBox<T, AllocatedByRust>

Allocates memory in PostgreSQL and then places val into it.

This value is managed by Rust, so gets dropped via normal Drop semantics.

If you need to give the boxed pointer to Postgres, call .into_pg().

use pgx::{PgBox, AllocatedByRust};

let ptr: PgBox<i32, AllocatedByRust> = PgBox::new(5);
assert_eq!(*ptr, 5);

let mut ptr: PgBox<Vec<i32>, AllocatedByRust> = PgBox::new(vec![]);
assert_eq!(*ptr, Vec::<i32>::default());

ptr.push(1);
assert_eq!(*ptr, vec![1]);
    
ptr.push(2);
assert_eq!(*ptr, vec![1, 2]);

ptr.push(3);
assert_eq!(*ptr, vec![1, 2, 3]);

let drained = ptr.drain(..).collect::<Vec<_>>();
assert_eq!(drained, vec![1, 2, 3])

pub fn new_in_context(
    val: T,
    memory_context: PgMemoryContexts
) -> PgBox<T, AllocatedByRust>

Allocates memory in PostgreSQL and then places val into it.

This value is managed by Rust, so gets dropped via normal Drop semantics.

If you need to give the boxed pointer to Postgres, call .into_pg().

use pgx::{PgBox, PgMemoryContexts, AllocatedByRust};

let ptr: PgBox<i32, AllocatedByRust> = PgBox::new_in_context(5, PgMemoryContexts::CurrentMemoryContext);
assert_eq!(*ptr, 5);

impl<T, AllocatedBy: WhoAllocated<T>> PgBox<T, AllocatedBy>

pub unsafe fn from_rust(ptr: *mut T) -> PgBox<T, AllocatedByRust>

Box a pointer that was allocated within Rust

When this PgBox<T> is dropped, the boxed memory is freed. Since Rust allocated it, Rust is responsible for freeing it.

If you need to give the boxed pointer to Postgres, call .into_pg()

pub fn alloc() -> PgBox<T, AllocatedByRust>

Allocate enough memory for the type’d struct, within Postgres’ CurrentMemoryContext The allocated memory is uninitialized.

When this object is dropped the backing memory will be pfree’d, unless it is instead turned into_pg(), at which point it will be freeded when its owning MemoryContext is deleted by Postgres (likely transaction end).

Examples

use pgx::{PgBox, pg_sys};
let ctid = PgBox::<pg_sys::ItemPointerData>::alloc();

pub fn alloc0() -> PgBox<T, AllocatedByRust>

Allocate enough memory for the type’d struct, within Postgres’ CurrentMemoryContext The allocated memory is zero-filled.

When this object is dropped the backing memory will be pfree’d, unless it is instead turned into_pg(), at which point it will be freeded when its owning MemoryContext is deleted by Postgres (likely transaction end).

Examples

use pgx::{PgBox, pg_sys};
let ctid = PgBox::<pg_sys::ItemPointerData>::alloc0();

pub fn alloc_in_context(
    memory_context: PgMemoryContexts
) -> PgBox<T, AllocatedByRust>

Allocate enough memory for the type’d struct, within the specified Postgres MemoryContext. The allocated memory is uninitalized.

When this object is dropped the backing memory will be pfree’d, unless it is instead turned into_pg(), at which point it will be freeded when its owning MemoryContext is deleted by Postgres (likely transaction end).

Examples

use pgx::{PgBox, pg_sys, PgMemoryContexts};
let ctid = PgBox::<pg_sys::ItemPointerData>::alloc_in_context(PgMemoryContexts::TopTransactionContext);

pub fn alloc0_in_context(
    memory_context: PgMemoryContexts
) -> PgBox<T, AllocatedByRust>

Allocate enough memory for the type’d struct, within the specified Postgres MemoryContext. The allocated memory is zero-filled.

When this object is dropped the backing memory will be pfree’d, unless it is instead turned into_pg(), at which point it will be freeded when its owning MemoryContext is deleted by Postgres (likely transaction end).

Examples

use pgx::{PgBox, pg_sys, PgMemoryContexts};
let ctid = PgBox::<pg_sys::ItemPointerData>::alloc0_in_context(PgMemoryContexts::TopTransactionContext);

pub fn alloc_node(node_tag: NodeTag) -> PgBox<T, AllocatedByRust>

Allocate a Postgres pg_sys::Node subtype, using palloc in the CurrentMemoryContext.

The allocated node will have it’s type_ field set to the node_tag argument, and will otherwise be initialized with all zeros

Examples

use pgx::{PgBox, pg_sys};
let create_trigger_statement = PgBox::<pg_sys::CreateTrigStmt>::alloc_node(pg_sys::NodeTag_T_CreateTrigStmt);

pub fn null() -> PgBox<T, AllocatedByPostgres>

Box nothing

pub fn is_null(&self) -> bool

Are we boxing a NULL?

pub fn as_ptr(&self) -> *mut T

Return the boxed pointer, so that it can be passed back into a Postgres function

pub fn into_pg(self) -> *mut T

Useful for returning the boxed pointer back to Postgres (as a return value, for example).

The boxed pointer is not free’d by Rust

pub fn into_pg_boxed(self) -> PgBox<T, AllocatedByPostgres>

Useful for returning the boxed pointer back to Postgres (as a return value, for example).

The boxed pointer is not free’d by Rust

pub unsafe fn with<F: FnOnce(&mut PgBox<T>)>(ptr: *mut T, func: F)

Execute a closure with a mutable, PgBox’d form of the specified ptr

Trait Implementations

impl<T, AllocatedBy: WhoAllocated<T>> Deref for PgBox<T, AllocatedBy>

type Target = T

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl<T, AllocatedBy: WhoAllocated<T>> DerefMut for PgBox<T, AllocatedBy>

fn deref_mut(&mut self) -> &mut T

Mutably dereferences the value.

impl<T, AllocatedBy: WhoAllocated<T>> Drop for PgBox<T, AllocatedBy>

fn drop(&mut self)

Executes the destructor for this type.

impl<T> FromDatum for PgBox<T, AllocatedByPostgres>

for user types

const NEEDS_TYPID: bool

unsafe fn from_datum(datum: Datum, is_null: bool, _: Oid) -> Option<Self>

Safety

unsafe fn from_datum_in_memory_context(
    memory_context: PgMemoryContexts,
    datum: usize,
    is_null: bool,
    _typoid: u32
) -> Option<Self> where
    Self: Sized, 

Default implementation switched to the specified memory context and then simply calls From::from_datum(...) from within that context.

impl<T, AllocatedBy: WhoAllocated<T>> IntoDatum for PgBox<T, AllocatedBy>

for user types

fn into_datum(self) -> Option<Datum>

fn type_oid() -> Oid

fn array_type_oid() -> Oid