Struct pgx::bgworkers::BackgroundWorkerBuilder

pub struct BackgroundWorkerBuilder { /* fields omitted */ }

A builder-style interface for creating a new Background Worker

This must be used from within your extension's _PG_init() function, finishing with the .load() function.

Example

use pgx::bgworkers::BackgroundWorkerBuilder;
use pgx::*;

pg_module_magic!();

#[pg_guard]
pub extern "C" fn _PG_init() {
    BackgroundWorkerBuilder::new("My Example BGWorker")
        .set_function("background_worker_main")
        .set_library("example")
        .enable_spi_access()
        .load();
}

#[pg_guard]
pub extern "C" fn background_worker_main(_arg: pg_sys::Datum) {
    // do bgworker stuff here
}

Implementations

impl BackgroundWorkerBuilder

pub fn new(name: &str) -> BackgroundWorkerBuilder

Construct a new BackgroundWorker of the specified name

By default, its type is also set to the specified name and it is configured to - start at BgWorkerStartTime::PostmasterStart. - never restart in the event it crashes

pub fn set_type(mut self: Self, input: &str) -> Self

What is the type of this BackgroundWorker

pub fn enable_shmem_access(
    mut self: Self,
    startup: Option<unsafe extern "C" fn()>
) -> Self

Does this BackgroundWorker want Shared Memory access?

pub fn enable_spi_access(mut self: Self) -> Self

Does this BackgroundWorker intend to use SPI?

If set, then the configured start time becomes BgWorkerStartTIme::RecoveryFinished as accessing SPI prior to possible database recovery is not possible

pub fn set_start_time(mut self: Self, input: BgWorkerStartTime) -> Self

When should this BackgroundWorker be started by Postgres?

pub fn set_restart_time(mut self: Self, input: Option<Duration>) -> Self

the interval, in seconds, that postgres should wait before restarting the process, in case it crashes. It can be Some(any positive duration value), or None`, indicating not to restart the process in case of a crash.

pub fn set_library(mut self: Self, input: &str) -> Self

What is the library name that contains the "main" function?

Typically, this will just be your extension's name

pub fn set_function(mut self: Self, input: &str) -> Self

What is the "main" function that should be run when the BackgroundWorker process is started?

The specified function must be: - extern "C", - guarded with #[pg_guard], - take 1 argument of type pgx::pg_sys::Datum, and - return "void"

Example

use pgx::*;

#[pg_guard]
pub extern "C" fn background_worker_main(_arg: pg_sys::Datum) {
}

pub fn set_argument(mut self: Self, input: Option<Datum>) -> Self

Datum argument to the background worker main function. This main function should take a single argument of type Datum and return void. bgw_main_arg will be passed as the argument. In addition, the global variable MyBgworkerEntry points to a copy of the BackgroundWorker structure passed at registration time; the worker may find it helpful to examine this structure.

On Windows (and anywhere else where EXEC_BACKEND is defined) or in dynamic background workers it is not safe to pass a Datum by reference, only by value. If an argument is required, it is safest to pass an int32 or other small value and use that as an index into an array allocated in shared memory.

Important

If a value like a cstring or text is passed then the pointer won't be valid from the new background worker process.

In general, this means that you should stick to primitive Rust types such as i32, bool, etc.

You you use pgx's IntoDatum trait to make the conversion into a datum easy:

use pgx::bgworkers::BackgroundWorkerBuilder;
use pgx::IntoDatum;
BackgroundWorkerBuilder::new("Example")
    .set_function("background_worker_main")
    .set_library("example")
    .set_argument(42i32.into_datum())
    .load();

pub fn set_extra(mut self: Self, input: &str) -> Self

extra data to be passed to the background worker. Unlike bgw_main_arg, this data is not passed as an argument to the worker's main function, but it can be accessed via the BackgroundWorker struct.

pub fn set_notify_pid(mut self: Self, input: i32) -> Self

PID of a PostgreSQL backend process to which the postmaster should send SIGUSR1 when the process is started or exits. It should be 0 for workers registered at postmaster startup time, or when the backend registering the worker does not wish to wait for the worker to start up. Otherwise, it should be initialized to pgx::pg_sys::MyProcPid

pub fn load(self)

Once properly configured, call load() to get the BackgroundWorker registered and started at the proper time by Postgres.