Struct PgBox

pub struct PgBox<T, AllocatedBy: WhoAllocated = 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::prelude::*;

pub fn do_something() -> pg_sys::ItemPointer {
    // postgres-allocate an ItemPointerData structure
    let mut tid = unsafe { 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::prelude::*;

pub fn do_something()  {
    // postgres-allocate an ItemPointerData structure
    let mut tid = unsafe { 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::prelude::*;

pub fn do_something()  {
    // open a relation and project it as a pg_sys::Relation
    let relid: pg_sys::Oid = example_rel_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 comes 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, AllocatedBy: WhoAllocated> 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 unsafe 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 = unsafe { PgBox::<pg_sys::ItemPointerData>::alloc() };

Safety

This function is unsafe as we cannot ensure that the MemoryContext used to allocate will live as long as Rust’s borrow checker expects it to.

It is also unsafe because the allocated T will be uninitialized and that may or may not be a valid state for T.

pub unsafe 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 = unsafe { PgBox::<pg_sys::ItemPointerData>::alloc0() };

Safety

This function is unsafe as we cannot ensure that the MemoryContext used to allocate will live as long as Rust’s borrow checker expects it to.

It is also unsafe because the allocated T’s memory will be zerod and that may or may not be a valid state for T.

pub unsafe 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 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, PgMemoryContexts};
let ctid = unsafe { PgBox::<pg_sys::ItemPointerData>::alloc_in_context(PgMemoryContexts::TopTransactionContext) };

Safety

This function is unsafe as we cannot ensure that the MemoryContext used to allocate will live as long as Rust’s borrow checker expects it to.

It is also unsafe because the allocated T will be uninitialized and that may or may not be a valid state for T.

pub unsafe 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 = unsafe { PgBox::<pg_sys::ItemPointerData>::alloc0_in_context(PgMemoryContexts::TopTransactionContext) };

Safety

This function is unsafe as we cannot ensure that the MemoryContext used to allocate will live as long as Rust’s borrow checker expects it to.

It is also unsafe because the allocated T’s memory will be zeroed and that may or may not be a valid state for T.

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

where T: PgNode,

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 = unsafe { PgBox::<pg_sys::CreateTrigStmt>::alloc_node(pg_sys::NodeTag_T_CreateTrigStmt) };

Safety

This function is unsafe as we cannot ensure that the MemoryContext used to allocate will live as long as Rust’s borrow checker expects it to.

It is also the caller’s responsibility to ensure the node_tag is the correct value for the pg_sys::PgNode type T: pg_sys::PgNode being used here.

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

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

Safety

This function is unsafe as we cannot ensure that ptr is a valid pointer that can be wrapped with PgBox.

Trait Implementations

impl<T, AllocatedBy: WhoAllocated> 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> DerefMut for PgBox<T, AllocatedBy>

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

Mutably dereferences the value.

impl<T, AllocatedBy: WhoAllocated> 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

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

Like from_datum for instantiating polymorphic types which require preserving the dynamic type metadata.

unsafe fn from_datum_in_memory_context( memory_context: PgMemoryContexts, datum: Datum, is_null: bool, _typoid: Oid, ) -> Option<Self>

where Self: Sized,

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

const GET_TYPOID: bool = false

Should a type OID be fetched when calling from_datum?

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

where Self: Sized,

Safety

unsafe fn try_from_datum( datum: Datum, is_null: bool, type_oid: Oid, ) -> Result<Option<Self>, TryFromDatumError>

where Self: Sized + IntoDatum,

try_from_datum is a convenience wrapper around FromDatum::from_datum that returns a a Result around an Option, as a Datum can be null. It’s intended to be used in situations where the caller needs to know whether the type conversion succeeded or failed.

unsafe fn try_from_datum_in_memory_context( memory_context: PgMemoryContexts, datum: Datum, is_null: bool, type_oid: Oid, ) -> Result<Option<Self>, TryFromDatumError>

where Self: Sized + IntoDatum,

A version of try_from_datum that switches to the given context to convert from Datum

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

for user types

fn into_datum(self) -> Option<Datum>

fn type_oid() -> Oid

fn composite_type_oid(&self) -> Option<Oid>

fn array_type_oid() -> Oid

fn is_compatible_with(other: Oid) -> bool

Is a Datum of this type compatible with another Postgres type?

impl<T: SqlTranslatable> SqlTranslatable for PgBox<T, AllocatedByPostgres>

fn argument_sql() -> Result<SqlMapping, ArgumentError>

fn return_sql() -> Result<Returns, ReturnsError>

fn type_name() -> &'static str

fn variadic() -> bool

fn optional() -> bool

fn entity() -> FunctionMetadataTypeEntity

impl<T: SqlTranslatable> SqlTranslatable for PgBox<T, AllocatedByRust>

fn argument_sql() -> Result<SqlMapping, ArgumentError>

fn return_sql() -> Result<Returns, ReturnsError>

fn type_name() -> &'static str

fn variadic() -> bool

fn optional() -> bool

fn entity() -> FunctionMetadataTypeEntity