\echo Use"CREATE EXTENSION worker_spi" to load this file. \quit

CREATEFUNCTIONworker_spi_launch(pg_catalog.int4)

RETURNSpg_catalog.bool STRICT

RETURNSpg_catalog.int4 STRICT

LANGUAGE C;

{

int32i=PG_GETARG_INT32(0);

BackgroundWorkerworker;

BackgroundWorkerHandle*handle;

BgwHandleStatusstatus;

pid_tpid;

worker.bgw_flags=BGWORKER_SHMEM_ACCESS |

BGWORKER_BACKEND_DATABASE_CONNECTION;

sprintf(worker.bgw_function_name,"worker_spi_main");

snprintf(worker.bgw_name,BGW_MAXLEN,"worker %d",i);

worker.bgw_main_arg=Int32GetDatum(i);

PG_RETURN_BOOL(RegisterDynamicBackgroundWorker(&worker));

worker.bgw_notify_pid=MyProcPid;

if (!RegisterDynamicBackgroundWorker(&worker,&handle))

PG_RETURN_NULL();

status=WaitForBackgroundWorkerStartup(handle,&pid);

if (status==BGWH_STOPPED)

ereport(ERROR,

(errcode(ERRCODE_INSUFFICIENT_RESOURCES),

errmsg("could not start background process"),

errhint("More details may be available in the server log.")));

if (status==BGWH_POSTMASTER_DIED)

ereport(ERROR,

(errcode(ERRCODE_INSUFFICIENT_RESOURCES),

errmsg("cannot start background processes without postmaster"),

errhint("Kill all remaining database processes and restart the database.")));

Assert(status==BGWH_STARTED);

PG_RETURN_INT32(pid);

}

<function>RegisterBackgroundWorker(<type>BackgroundWorker *worker</type>)</function>

from its <function>_PG_init()</>. Background workers can also be started

after the system is up and running by calling the function

<function>RegisterDynamicBackgroundWorker</function>(<type>BackgroundWorker

*worker</type>). Unlike <function>RegisterBackgroundWorker</>, which can

only be called from within the postmaster,

<function>RegisterDynamicBackgroundWorker</function> must be called from

a regular backend.

<function>RegisterDynamicBackgroundWorker(<type>BackgroundWorker

*worker, BackgroundWorkerHandle **handle</type>)</function>. Unlike

<function>RegisterBackgroundWorker</>, which canonly be called from within

the postmaster,<function>RegisterDynamicBackgroundWorker</function> must be

called froma regular backend.

</para>

<para>

char bgw_library_name[BGW_MAXLEN]; /* only if bgw_main is NULL */

char bgw_function_name[BGW_MAXLEN]; /* only if bgw_main is NULL */

Datum bgw_main_arg;

int bgw_notify_pid;

} BackgroundWorker;

</programlisting>

</para>

<structfield>bgw_main</structfield> is NULL.

</para>

<para>

<structfield>bgw_notify_pid</structfield> is the PID of a PostgreSQL

backend process to which the postmaster should send <literal>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 <literal>MyProcPid</>.

</para>

<para>Once running, the process can connect to a database by calling

<function>BackgroundWorkerInitializeConnection(<parameter>char *dbname</parameter>, <parameter>char *username</parameter>)</function>.

This allows the process to run transactions and queries using the

<command>postgres</> itself has terminated.

</para>

<para>

When a background worker is registered using the

<function>RegisterDynamicBackgroundWorker</function> function, it is

possible for the backend performing the registration to obtain information

the status of the worker. Backends wishing to do this should pass the

address of a <type>BackgroundWorkerHandle *</type> as the second argument

to <function>RegisterDynamicBackgroundWorker</function>. If the worker

is successfully registered, this pointer will be initialized with an

opaque handle that can subsequently be passed to

<function>GetBackgroundWorkerPid(<parameter>BackgroundWorkerHandle *</parameter>, <parameter>pid_t *</parameter>)</function>.

This function can be used to poll the status of the worker: a return

value of <literal>BGWH_NOT_YET_STARTED</> indicates that the worker has not

yet been started by the postmaster; <literal>BGWH_STOPPED</literal>

indicates that it has been started but is no longer running; and

<literal>BGWH_STARTED</literal> indicates that it is currently running.

In this last case, the PID will also be returned via the second argument.

</para>

<para>

In some cases, a process which registers a background worker may wish to

wait for the worker to start up. This can be accomplished by initializing

<structfield>bgw_notify_pid</structfield> to <literal>MyProcPid</> and

then passing the <type>BackgroundWorkerHandle *</type> obtained at

registration time to

<function>WaitForBackgroundWorkerStartup(<parameter>BackgroundWorkerHandle

*handle</parameter>, <parameter>pid_t *</parameter>)</function> function.

This function will block until the postmaster has attempted to start the

background worker, or until the postmaster dies. If the background runner

is running, the return value will <literal>BGWH_STARTED</>, and

the PID will be written to the provided address. Otherwise, the return

value will be <literal>BGWH_STOPPED</literal> or

<literal>BGWH_POSTMASTER_DIED</literal>.

</para>

<para>

The <filename>worker_spi</> contrib module contains a working example,

which demonstrates some useful techniques.

QueuePositionpos;/* backend has read queue up to here */

}QueueBackendStatus;

#defineInvalidPid(-1)