Struct pgrx::bgworkers::BackgroundWorkerBuilder

pub struct BackgroundWorkerBuilder { /* private fields */ }

A builder-style interface for creating a new Background Worker

For a static background worker, this must be used from within your extension’s _PG_init() function, finishing with the .load() function. Dynamic background workers are loaded with .load_dynamic() and have no restriction as to where they can be loaded.

Example

use pgrx::prelude::*;
use pgrx::bgworkers::BackgroundWorkerBuilder;

#[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(self, input: &str) -> Self

What is the type of this BackgroundWorker

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

Does this BackgroundWorker want Shared Memory access?

startup allows specifying shared memory initialization startup hook. Ignored if BackgroundWorkerBuilder::load_dynamic is used.

pub fn enable_spi_access(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(self, input: BgWorkerStartTime) -> Self

When should this BackgroundWorker be started by Postgres?

pub fn set_restart_time(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(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(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 pgrx::pg_sys::Datum, and - return “void”

Example

use pgrx::prelude::*;

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

pub fn set_argument(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 pgrx’s IntoDatum trait to make the conversion into a datum easy:

use pgrx::prelude::*;
use pgrx::bgworkers::BackgroundWorkerBuilder;

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

pub fn set_extra(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(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 pgrx::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.

pub fn load_dynamic(self) -> DynamicBackgroundWorker

Once properly configured, call load_dynamic() to get the BackgroundWorker registered and started dynamically.

Trait Implementations

impl<'a> Into<BackgroundWorker> for &'a BackgroundWorkerBuilder

This conversion is useful only in limited context outside of pgrx, such as when this structure is required by other libraries and the worker is not to be started by pgrx itself. In this case, the builder is useful for building this structure.

fn into(self) -> BackgroundWorker

Converts this type into the (usually inferred) input type.