PgBackgroundWorker

Namespace: Ankus

Assembly: Ankus.Runtime.dll

Registers PostgreSQL background workers and supplies operations for a generated worker entry.

public static class PgBackgroundWorker

Backend operations are synchronous and remain on the owning PostgreSQL thread. Generated entries receive shared-memory access; database work requires a connection and a transaction callback.

Inheritance: object

Methods

AttachSignalHandlers(PgBackgroundWorkerSignals)

Adds native signal observers before unblocking signals in the worker.

public static void AttachSignalHandlers(PgBackgroundWorkerSignals signals)

Parameters:

signals — PgBackgroundWorkerSignals

The desired signals; reload and termination observers always remain installed.

Observing Interrupt replaces PostgreSQL’s SIGINT query-cancellation handler. Without that observer, SIGINT can cancel an active worker transaction.

Connect(string?, string?)

Initializes this worker’s database connection by name, once per worker process.

public static void Connect(string? database, string? user = null)

Parameters:

database — string

The database name, or null for a connection without a selected database.

user — string

The role name, or null for PostgreSQL’s bootstrap superuser.

Connect(uint, uint)

Initializes this worker’s database connection by OID, once per worker process.

public static void Connect(uint databaseOid, uint userOid = 0)

Parameters:

databaseOid — uint

The database OID, or zero for no selected database.

userOid — uint

The role OID, or zero for PostgreSQL’s bootstrap superuser.

ConsumeSignals(PgBackgroundWorkerSignals)

Returns and clears selected pending signal observations.

public static PgBackgroundWorkerSignals ConsumeSignals(PgBackgroundWorkerSignals signals = PgBackgroundWorkerSignals.Reload | PgBackgroundWorkerSignals.Terminate | PgBackgroundWorkerSignals.Interrupt | PgBackgroundWorkerSignals.Child)

Parameters:

signals — PgBackgroundWorkerSignals

The observations to consume.

Returns: PgBackgroundWorkerSignals

The selected signals received since their previous consumption.

Register(PgBackgroundWorkerOptions)

Registers a static worker during shared preload; backend replay of shared preload does not register it again.

public static void Register(PgBackgroundWorkerOptions options)

Parameters:

options — PgBackgroundWorkerOptions

The complete worker declaration.

ReloadConfiguration()

Reloads PostgreSQL configuration within the current worker after a reload notification.

public static void ReloadConfiguration()

RunTransaction(Action)

Executes synchronous database work in a new worker transaction and commits when the callback returns.

public static void RunTransaction(Action action)

Parameters:

action — Action

The synchronous transaction body.

A canceled callback always rolls back. Its caller can catch PgQueryCanceledException after rollback and continue the worker; catching cancellation inside the callback cannot commit it. FATAL and PANIC reports still terminate the worker. Nested worker transactions are rejected.

RunTransaction<TResult>(Func<TResult>)

Executes synchronous database work in a new worker transaction and returns its owned result after commit.

public static TResult RunTransaction<TResult>(Func<TResult> action)

Type parameters:

TResult

The owned result.

Parameters:

action — Func<TResult>

The synchronous transaction body.

Returns: TResult

The callback result after successful commit.

Failure aborts the transaction before the original managed exception or owned PostgreSQL error returns. Query cancellation remains pending throughout the callback, even if caught there. After rollback, the caller can catch PgQueryCanceledException and start another transaction. FATAL and PANIC reports still terminate the worker. Nested worker transactions are rejected.

TryStart(PgBackgroundWorkerOptions, out PgBackgroundWorkerHandle?)

Attempts to register a dynamic worker, returning false when PostgreSQL has no available worker slot.

public static bool TryStart(PgBackgroundWorkerOptions options, out PgBackgroundWorkerHandle? worker)

Parameters:

options — PgBackgroundWorkerOptions

The complete worker declaration.

worker — PgBackgroundWorkerHandle

The callback-owned observation handle when registration succeeds.

Returns: bool

Whether PostgreSQL accepted the registration.

Registration does not guarantee startup. Inspect or wait on the handle to observe the process. PostgreSQL can register the worker before allocating its observation handle. An allocation error can therefore throw while the worker remains registered; retrying may start another worker. Dynamic registration requires an initialized backend after shared preload has completed. Disposing the handle or leaving this backend callback does not terminate the registered worker. PostgreSQL sanitizes dynamic names, types, library paths and symbols; values it would alter are rejected. Extra text preserves UTF-8 independently of those metadata restrictions.

Wait(TimeSpan?)

Waits on the worker’s latch, returning false for postmaster death or termination, even after consuming its observation.

public static bool Wait(TimeSpan? timeout = null)

Parameters:

timeout — TimeSpan?

A whole-millisecond timeout, or null to wait indefinitely.

Returns: bool

Whether the worker may continue after waking.

Exceptions:

• PgQueryCanceledException: PostgreSQL cancels the wait through its default SIGINT handler.

Cancellation outside a transaction ends only this wait and can be caught before waiting or starting a transaction again. Inside RunTransaction, cancellation still requires the transaction to abort before the worker resumes.

Properties

CanContinue

Gets whether the postmaster is alive and termination has not been requested.

public static bool CanContinue { get; }

Value: bool

Extra

Gets the extra text copied into the current worker’s registration.

public static string Extra { get; }

Value: string

Name

Gets the current worker’s name as an owned string.

public static string Name { get; }

Value: string

Type

Gets the current worker’s type as an owned string.

public static string Type { get; }

Value: string