PostgreSQL Source Code  git master
 All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros
bgworker.c
Go to the documentation of this file.
1 /*--------------------------------------------------------------------
2  * bgworker.c
3  * POSTGRES pluggable background workers implementation
4  *
5  * Portions Copyright (c) 1996-2017, PostgreSQL Global Development Group
6  *
7  * IDENTIFICATION
8  * src/backend/postmaster/bgworker.c
9  *
10  *-------------------------------------------------------------------------
11  */
12 
13 #include "postgres.h"
14 
15 #include <unistd.h>
16 
17 #include "libpq/pqsignal.h"
18 #include "miscadmin.h"
19 #include "pgstat.h"
20 #include "port/atomics.h"
22 #include "postmaster/postmaster.h"
24 #include "storage/dsm.h"
25 #include "storage/ipc.h"
26 #include "storage/latch.h"
27 #include "storage/lwlock.h"
28 #include "storage/pg_shmem.h"
29 #include "storage/pmsignal.h"
30 #include "storage/proc.h"
31 #include "storage/procsignal.h"
32 #include "storage/shmem.h"
33 #include "tcop/tcopprot.h"
34 #include "utils/ascii.h"
35 #include "utils/ps_status.h"
36 #include "utils/timeout.h"
37 
38 /*
39  * The postmaster's list of registered background workers, in private memory.
40  */
42 
43 /*
44  * BackgroundWorkerSlots exist in shared memory and can be accessed (via
45  * the BackgroundWorkerArray) by both the postmaster and by regular backends.
46  * However, the postmaster cannot take locks, even spinlocks, because this
47  * might allow it to crash or become wedged if shared memory gets corrupted.
48  * Such an outcome is intolerable. Therefore, we need a lockless protocol
49  * for coordinating access to this data.
50  *
51  * The 'in_use' flag is used to hand off responsibility for the slot between
52  * the postmaster and the rest of the system. When 'in_use' is false,
53  * the postmaster will ignore the slot entirely, except for the 'in_use' flag
54  * itself, which it may read. In this state, regular backends may modify the
55  * slot. Once a backend sets 'in_use' to true, the slot becomes the
56  * responsibility of the postmaster. Regular backends may no longer modify it,
57  * but the postmaster may examine it. Thus, a backend initializing a slot
58  * must fully initialize the slot - and insert a write memory barrier - before
59  * marking it as in use.
60  *
61  * As an exception, however, even when the slot is in use, regular backends
62  * may set the 'terminate' flag for a slot, telling the postmaster not
63  * to restart it. Once the background worker is no longer running, the slot
64  * will be released for reuse.
65  *
66  * In addition to coordinating with the postmaster, backends modifying this
67  * data structure must coordinate with each other. Since they can take locks,
68  * this is straightforward: any backend wishing to manipulate a slot must
69  * take BackgroundWorkerLock in exclusive mode. Backends wishing to read
70  * data that might get concurrently modified by other backends should take
71  * this lock in shared mode. No matter what, backends reading this data
72  * structure must be able to tolerate concurrent modifications by the
73  * postmaster.
74  */
75 typedef struct BackgroundWorkerSlot
76 {
77  bool in_use;
78  bool terminate;
79  pid_t pid; /* InvalidPid = not started yet; 0 = dead */
80  uint64 generation; /* incremented when slot is recycled */
83 
84 /*
85  * In order to limit the total number of parallel workers (according to
86  * max_parallel_workers GUC), we maintain the number of active parallel
87  * workers. Since the postmaster cannot take locks, two variables are used for
88  * this purpose: the number of registered parallel workers (modified by the
89  * backends, protected by BackgroundWorkerLock) and the number of terminated
90  * parallel workers (modified only by the postmaster, lockless). The active
91  * number of parallel workers is the number of registered workers minus the
92  * terminated ones. These counters can of course overflow, but it's not
93  * important here since the subtraction will still give the right number.
94  */
95 typedef struct BackgroundWorkerArray
96 {
100  BackgroundWorkerSlot slot[FLEXIBLE_ARRAY_MEMBER];
102 
104 {
105  int slot;
106  uint64 generation;
107 };
108 
110 
111 /*
112  * List of workers that are allowed to be started outside of
113  * shared_preload_libraries.
114  */
117  NULL
118 };
119 
120 /*
121  * Calculate shared memory needed.
122  */
123 Size
125 {
126  Size size;
127 
128  /* Array of workers is variably sized. */
129  size = offsetof(BackgroundWorkerArray, slot);
131  sizeof(BackgroundWorkerSlot)));
132 
133  return size;
134 }
135 
136 /*
137  * Initialize shared memory.
138  */
139 void
141 {
142  bool found;
143 
144  BackgroundWorkerData = ShmemInitStruct("Background Worker Data",
146  &found);
147  if (!IsUnderPostmaster)
148  {
149  slist_iter siter;
150  int slotno = 0;
151 
152  BackgroundWorkerData->total_slots = max_worker_processes;
153  BackgroundWorkerData->parallel_register_count = 0;
154  BackgroundWorkerData->parallel_terminate_count = 0;
155 
156  /*
157  * Copy contents of worker list into shared memory. Record the shared
158  * memory slot assigned to each worker. This ensures a 1-to-1
159  * correspondence between the postmaster's private list and the array
160  * in shared memory.
161  */
162  slist_foreach(siter, &BackgroundWorkerList)
163  {
164  BackgroundWorkerSlot *slot = &BackgroundWorkerData->slot[slotno];
165  RegisteredBgWorker *rw;
166 
167  rw = slist_container(RegisteredBgWorker, rw_lnode, siter.cur);
168  Assert(slotno < max_worker_processes);
169  slot->in_use = true;
170  slot->terminate = false;
171  slot->pid = InvalidPid;
172  slot->generation = 0;
173  rw->rw_shmem_slot = slotno;
174  rw->rw_worker.bgw_notify_pid = 0; /* might be reinit after crash */
175  memcpy(&slot->worker, &rw->rw_worker, sizeof(BackgroundWorker));
176  ++slotno;
177  }
178 
179  /*
180  * Mark any remaining slots as not in use.
181  */
182  while (slotno < max_worker_processes)
183  {
184  BackgroundWorkerSlot *slot = &BackgroundWorkerData->slot[slotno];
185 
186  slot->in_use = false;
187  ++slotno;
188  }
189  }
190  else
191  Assert(found);
192 }
193 
194 /*
195  * Search the postmaster's backend-private list of RegisteredBgWorker objects
196  * for the one that maps to the given slot number.
197  */
198 static RegisteredBgWorker *
200 {
201  slist_iter siter;
202 
203  slist_foreach(siter, &BackgroundWorkerList)
204  {
205  RegisteredBgWorker *rw;
206 
207  rw = slist_container(RegisteredBgWorker, rw_lnode, siter.cur);
208  if (rw->rw_shmem_slot == slotno)
209  return rw;
210  }
211 
212  return NULL;
213 }
214 
215 /*
216  * Notice changes to shared memory made by other backends. This code
217  * runs in the postmaster, so we must be very careful not to assume that
218  * shared memory contents are sane. Otherwise, a rogue backend could take
219  * out the postmaster.
220  */
221 void
223 {
224  int slotno;
225 
226  /*
227  * The total number of slots stored in shared memory should match our
228  * notion of max_worker_processes. If it does not, something is very
229  * wrong. Further down, we always refer to this value as
230  * max_worker_processes, in case shared memory gets corrupted while we're
231  * looping.
232  */
233  if (max_worker_processes != BackgroundWorkerData->total_slots)
234  {
235  elog(LOG,
236  "inconsistent background worker state (max_worker_processes=%d, total_slots=%d",
238  BackgroundWorkerData->total_slots);
239  return;
240  }
241 
242  /*
243  * Iterate through slots, looking for newly-registered workers or workers
244  * who must die.
245  */
246  for (slotno = 0; slotno < max_worker_processes; ++slotno)
247  {
248  BackgroundWorkerSlot *slot = &BackgroundWorkerData->slot[slotno];
249  RegisteredBgWorker *rw;
250 
251  if (!slot->in_use)
252  continue;
253 
254  /*
255  * Make sure we don't see the in_use flag before the updated slot
256  * contents.
257  */
258  pg_read_barrier();
259 
260  /* See whether we already know about this worker. */
262  if (rw != NULL)
263  {
264  /*
265  * In general, the worker data can't change after it's initially
266  * registered. However, someone can set the terminate flag.
267  */
268  if (slot->terminate && !rw->rw_terminate)
269  {
270  rw->rw_terminate = true;
271  if (rw->rw_pid != 0)
272  kill(rw->rw_pid, SIGTERM);
273  else
274  {
275  /* Report never-started, now-terminated worker as dead. */
277  }
278  }
279  continue;
280  }
281 
282  /*
283  * If the worker is marked for termination, we don't need to add it to
284  * the registered workers list; we can just free the slot. However, if
285  * bgw_notify_pid is set, the process that registered the worker may
286  * need to know that we've processed the terminate request, so be sure
287  * to signal it.
288  */
289  if (slot->terminate)
290  {
291  int notify_pid;
292 
293  /*
294  * We need a memory barrier here to make sure that the load of
295  * bgw_notify_pid and the update of parallel_terminate_count
296  * complete before the store to in_use.
297  */
298  notify_pid = slot->worker.bgw_notify_pid;
299  if ((slot->worker.bgw_flags & BGWORKER_CLASS_PARALLEL) != 0)
300  BackgroundWorkerData->parallel_terminate_count++;
302  slot->pid = 0;
303  slot->in_use = false;
304  if (notify_pid != 0)
305  kill(notify_pid, SIGUSR1);
306 
307  continue;
308  }
309 
310  /*
311  * Copy the registration data into the registered workers list.
312  */
313  rw = malloc(sizeof(RegisteredBgWorker));
314  if (rw == NULL)
315  {
316  ereport(LOG,
317  (errcode(ERRCODE_OUT_OF_MEMORY),
318  errmsg("out of memory")));
319  return;
320  }
321 
322  /*
323  * Copy strings in a paranoid way. If shared memory is corrupted, the
324  * source data might not even be NUL-terminated.
325  */
327  slot->worker.bgw_name, BGW_MAXLEN);
332 
333  /*
334  * Copy various fixed-size fields.
335  *
336  * flags, start_time, and restart_time are examined by the postmaster,
337  * but nothing too bad will happen if they are corrupted. The
338  * remaining fields will only be examined by the child process. It
339  * might crash, but we won't.
340  */
341  rw->rw_worker.bgw_flags = slot->worker.bgw_flags;
344  rw->rw_worker.bgw_main = slot->worker.bgw_main;
346  memcpy(rw->rw_worker.bgw_extra, slot->worker.bgw_extra, BGW_EXTRALEN);
347 
348  /*
349  * Copy the PID to be notified about state changes, but only if the
350  * postmaster knows about a backend with that PID. It isn't an error
351  * if the postmaster doesn't know about the PID, because the backend
352  * that requested the worker could have died (or been killed) just
353  * after doing so. Nonetheless, at least until we get some experience
354  * with how this plays out in the wild, log a message at a relative
355  * high debug level.
356  */
359  {
360  elog(DEBUG1, "worker notification PID %lu is not valid",
361  (long) rw->rw_worker.bgw_notify_pid);
362  rw->rw_worker.bgw_notify_pid = 0;
363  }
364 
365  /* Initialize postmaster bookkeeping. */
366  rw->rw_backend = NULL;
367  rw->rw_pid = 0;
368  rw->rw_child_slot = 0;
369  rw->rw_crashed_at = 0;
370  rw->rw_shmem_slot = slotno;
371  rw->rw_terminate = false;
372 
373  /* Log it! */
374  ereport(DEBUG1,
375  (errmsg("registering background worker \"%s\"",
376  rw->rw_worker.bgw_name)));
377 
378  slist_push_head(&BackgroundWorkerList, &rw->rw_lnode);
379  }
380 }
381 
382 /*
383  * Forget about a background worker that's no longer needed.
384  *
385  * The worker must be identified by passing an slist_mutable_iter that
386  * points to it. This convention allows deletion of workers during
387  * searches of the worker list, and saves having to search the list again.
388  *
389  * This function must be invoked only in the postmaster.
390  */
391 void
393 {
394  RegisteredBgWorker *rw;
395  BackgroundWorkerSlot *slot;
396 
397  rw = slist_container(RegisteredBgWorker, rw_lnode, cur->cur);
398 
400  slot = &BackgroundWorkerData->slot[rw->rw_shmem_slot];
402  BackgroundWorkerData->parallel_terminate_count++;
403 
404  slot->in_use = false;
405 
406  ereport(DEBUG1,
407  (errmsg("unregistering background worker \"%s\"",
408  rw->rw_worker.bgw_name)));
409 
411  free(rw);
412 }
413 
414 /*
415  * Report the PID of a newly-launched background worker in shared memory.
416  *
417  * This function should only be called from the postmaster.
418  */
419 void
421 {
422  BackgroundWorkerSlot *slot;
423 
425  slot = &BackgroundWorkerData->slot[rw->rw_shmem_slot];
426  slot->pid = rw->rw_pid;
427 
428  if (rw->rw_worker.bgw_notify_pid != 0)
429  kill(rw->rw_worker.bgw_notify_pid, SIGUSR1);
430 }
431 
432 /*
433  * Report that the PID of a background worker is now zero because a
434  * previously-running background worker has exited.
435  *
436  * This function should only be called from the postmaster.
437  */
438 void
440 {
441  RegisteredBgWorker *rw;
442  BackgroundWorkerSlot *slot;
443  int notify_pid;
444 
445  rw = slist_container(RegisteredBgWorker, rw_lnode, cur->cur);
446 
448  slot = &BackgroundWorkerData->slot[rw->rw_shmem_slot];
449  slot->pid = rw->rw_pid;
450  notify_pid = rw->rw_worker.bgw_notify_pid;
451 
452  /*
453  * If this worker is slated for deregistration, do that before notifying
454  * the process which started it. Otherwise, if that process tries to
455  * reuse the slot immediately, it might not be available yet. In theory
456  * that could happen anyway if the process checks slot->pid at just the
457  * wrong moment, but this makes the window narrower.
458  */
459  if (rw->rw_terminate ||
462 
463  if (notify_pid != 0)
464  kill(notify_pid, SIGUSR1);
465 }
466 
467 /*
468  * Cancel SIGUSR1 notifications for a PID belonging to an exiting backend.
469  *
470  * This function should only be called from the postmaster.
471  */
472 void
474 {
475  slist_iter siter;
476 
477  slist_foreach(siter, &BackgroundWorkerList)
478  {
479  RegisteredBgWorker *rw;
480 
481  rw = slist_container(RegisteredBgWorker, rw_lnode, siter.cur);
482  if (rw->rw_worker.bgw_notify_pid == pid)
483  rw->rw_worker.bgw_notify_pid = 0;
484  }
485 }
486 
487 /*
488  * Reset background worker crash state.
489  *
490  * We assume that, after a crash-and-restart cycle, background workers without
491  * the never-restart flag should be restarted immediately, instead of waiting
492  * for bgw_restart_time to elapse.
493  */
494 void
496 {
497  slist_mutable_iter iter;
498 
499  slist_foreach_modify(iter, &BackgroundWorkerList)
500  {
501  RegisteredBgWorker *rw;
502 
503  rw = slist_container(RegisteredBgWorker, rw_lnode, iter.cur);
504 
505  /*
506  * For workers that should not be restarted, we don't want to lose the
507  * information that they have crashed; otherwise, they would be
508  * restarted, which is wrong.
509  */
511  rw->rw_crashed_at = 0;
512  }
513 }
514 
515 #ifdef EXEC_BACKEND
516 /*
517  * In EXEC_BACKEND mode, workers use this to retrieve their details from
518  * shared memory.
519  */
521 BackgroundWorkerEntry(int slotno)
522 {
523  static BackgroundWorker myEntry;
524  BackgroundWorkerSlot *slot;
525 
526  Assert(slotno < BackgroundWorkerData->total_slots);
527  slot = &BackgroundWorkerData->slot[slotno];
528  Assert(slot->in_use);
529 
530  /* must copy this in case we don't intend to retain shmem access */
531  memcpy(&myEntry, &slot->worker, sizeof myEntry);
532  return &myEntry;
533 }
534 #endif
535 
536 /*
537  * Complain about the BackgroundWorker definition using error level elevel.
538  * Return true if it looks ok, false if not (unless elevel >= ERROR, in
539  * which case we won't return at all in the not-OK case).
540  */
541 static bool
543 {
544  /* sanity check for flags */
546  {
547  if (!(worker->bgw_flags & BGWORKER_SHMEM_ACCESS))
548  {
549  ereport(elevel,
550  (errcode(ERRCODE_INVALID_PARAMETER_VALUE),
551  errmsg("background worker \"%s\": must attach to shared memory in order to request a database connection",
552  worker->bgw_name)));
553  return false;
554  }
555 
557  {
558  ereport(elevel,
559  (errcode(ERRCODE_INVALID_PARAMETER_VALUE),
560  errmsg("background worker \"%s\": cannot request database access if starting at postmaster start",
561  worker->bgw_name)));
562  return false;
563  }
564 
565  /* XXX other checks? */
566  }
567 
568  if ((worker->bgw_restart_time < 0 &&
569  worker->bgw_restart_time != BGW_NEVER_RESTART) ||
570  (worker->bgw_restart_time > USECS_PER_DAY / 1000))
571  {
572  ereport(elevel,
573  (errcode(ERRCODE_INVALID_PARAMETER_VALUE),
574  errmsg("background worker \"%s\": invalid restart interval",
575  worker->bgw_name)));
576  return false;
577  }
578 
579  return true;
580 }
581 
582 static void
584 {
585  sigaddset(&BlockSig, SIGQUIT); /* prevent nested calls */
587 
588  /*
589  * We DO NOT want to run proc_exit() callbacks -- we're here because
590  * shared memory may be corrupted, so we don't want to try to clean up our
591  * transaction. Just nail the windows shut and get out of town. Now that
592  * there's an atexit callback to prevent third-party code from breaking
593  * things by calling exit() directly, we have to reset the callbacks
594  * explicitly to make this work as intended.
595  */
596  on_exit_reset();
597 
598  /*
599  * Note we do exit(2) not exit(0). This is to force the postmaster into a
600  * system reset cycle if some idiot DBA sends a manual SIGQUIT to a random
601  * backend. This is necessary precisely because we don't clean up our
602  * shared memory state. (The "dead man switch" mechanism in pmsignal.c
603  * should ensure the postmaster sees this as a crash, too, but no harm in
604  * being doubly sure.)
605  */
606  exit(2);
607 }
608 
609 /*
610  * Standard SIGTERM handler for background workers
611  */
612 static void
614 {
616 
617  ereport(FATAL,
618  (errcode(ERRCODE_ADMIN_SHUTDOWN),
619  errmsg("terminating background worker \"%s\" due to administrator command",
621 }
622 
623 /*
624  * Standard SIGUSR1 handler for unconnected workers
625  *
626  * Here, we want to make sure an unconnected worker will at least heed
627  * latch activity.
628  */
629 static void
631 {
632  int save_errno = errno;
633 
635 
636  errno = save_errno;
637 }
638 
639 /*
640  * Start a new background worker
641  *
642  * This is the main entry point for background worker, to be called from
643  * postmaster.
644  */
645 void
647 {
648  sigjmp_buf local_sigjmp_buf;
649  char buf[MAXPGPATH];
651  bgworker_main_type entrypt;
652 
653  if (worker == NULL)
654  elog(FATAL, "unable to find bgworker entry");
655 
656  IsBackgroundWorker = true;
657 
658  /* Identify myself via ps */
659  snprintf(buf, MAXPGPATH, "bgworker: %s", worker->bgw_name);
660  init_ps_display(buf, "", "", "");
661 
662  /*
663  * If we're not supposed to have shared memory access, then detach from
664  * shared memory. If we didn't request shared memory access, the
665  * postmaster won't force a cluster-wide restart if we exit unexpectedly,
666  * so we'd better make sure that we don't mess anything up that would
667  * require that sort of cleanup.
668  */
669  if ((worker->bgw_flags & BGWORKER_SHMEM_ACCESS) == 0)
670  {
671  dsm_detach_all();
673  }
674 
676 
677  /* Apply PostAuthDelay */
678  if (PostAuthDelay > 0)
679  pg_usleep(PostAuthDelay * 1000000L);
680 
681  /*
682  * Set up signal handlers.
683  */
685  {
686  /*
687  * SIGINT is used to signal canceling the current action
688  */
692 
693  /* XXX Any other handlers needed here? */
694  }
695  else
696  {
697  pqsignal(SIGINT, SIG_IGN);
699  pqsignal(SIGFPE, SIG_IGN);
700  }
701  pqsignal(SIGTERM, bgworker_die);
703 
705  InitializeTimeouts(); /* establishes SIGALRM handler */
706 
710 
711  /*
712  * If an exception is encountered, processing resumes here.
713  *
714  * See notes in postgres.c about the design of this coding.
715  */
716  if (sigsetjmp(local_sigjmp_buf, 1) != 0)
717  {
718  /* Since not using PG_TRY, must reset error stack by hand */
720 
721  /* Prevent interrupts while cleaning up */
722  HOLD_INTERRUPTS();
723 
724  /* Report the error to the server log */
725  EmitErrorReport();
726 
727  /*
728  * Do we need more cleanup here? For shmem-connected bgworkers, we
729  * will call InitProcess below, which will install ProcKill as exit
730  * callback. That will take care of releasing locks, etc.
731  */
732 
733  /* and go away */
734  proc_exit(1);
735  }
736 
737  /* We can now handle ereport(ERROR) */
738  PG_exception_stack = &local_sigjmp_buf;
739 
740  /*
741  * If the background worker request shared memory access, set that up now;
742  * else, detach all shared memory segments.
743  */
744  if (worker->bgw_flags & BGWORKER_SHMEM_ACCESS)
745  {
746  /*
747  * Early initialization. Some of this could be useful even for
748  * background workers that aren't using shared memory, but they can
749  * call the individual startup routines for those subsystems if
750  * needed.
751  */
752  BaseInit();
753 
754  /*
755  * Create a per-backend PGPROC struct in shared memory, except in the
756  * EXEC_BACKEND case where this was done in SubPostmasterMain. We must
757  * do this before we can use LWLocks (and in the EXEC_BACKEND case we
758  * already had to do some stuff with LWLocks).
759  */
760 #ifndef EXEC_BACKEND
761  InitProcess();
762 #endif
763  }
764 
765  /*
766  * If bgw_main is set, we use that value as the initial entrypoint.
767  * However, if the library containing the entrypoint wasn't loaded at
768  * postmaster startup time, passing it as a direct function pointer is not
769  * possible. To work around that, we allow callers for whom a function
770  * pointer is not available to pass a library name (which will be loaded,
771  * if necessary) and a function name (which will be looked up in the named
772  * library).
773  */
774  if (worker->bgw_main != NULL)
775  entrypt = worker->bgw_main;
776  else
777  entrypt = (bgworker_main_type)
779  worker->bgw_function_name,
780  true, NULL);
781 
782  /*
783  * Note that in normal processes, we would call InitPostgres here. For a
784  * worker, however, we don't know what database to connect to, yet; so we
785  * need to wait until the user code does it via
786  * BackgroundWorkerInitializeConnection().
787  */
788 
789  /*
790  * Now invoke the user-defined worker code
791  */
792  entrypt(worker->bgw_main_arg);
793 
794  /* ... and if it returns, we're done */
795  proc_exit(0);
796 }
797 
798 /*
799  * Register a new background worker while processing shared_preload_libraries.
800  *
801  * This can only be called in the _PG_init function of a module library
802  * that's loaded by shared_preload_libraries; otherwise it has no effect.
803  */
804 void
806 {
807  RegisteredBgWorker *rw;
808  static int numworkers = 0;
809  bool internal = false;
810  int i;
811 
812  if (!IsUnderPostmaster)
813  ereport(DEBUG1,
814  (errmsg("registering background worker \"%s\"", worker->bgw_name)));
815 
816  for (i = 0; InternalBGWorkers[i]; i++)
817  {
818  if (worker->bgw_main == InternalBGWorkers[i])
819  {
820  internal = true;
821  break;
822  }
823  }
824 
826  {
827  if (!IsUnderPostmaster)
828  ereport(LOG,
829  (errcode(ERRCODE_FEATURE_NOT_SUPPORTED),
830  errmsg("background worker \"%s\": must be registered in shared_preload_libraries",
831  worker->bgw_name)));
832  return;
833  }
834 
835  if (!SanityCheckBackgroundWorker(worker, LOG))
836  return;
837 
838  if (worker->bgw_notify_pid != 0)
839  {
840  ereport(LOG,
841  (errcode(ERRCODE_FEATURE_NOT_SUPPORTED),
842  errmsg("background worker \"%s\": only dynamic background workers can request notification",
843  worker->bgw_name)));
844  return;
845  }
846 
847  /*
848  * Enforce maximum number of workers. Note this is overly restrictive: we
849  * could allow more non-shmem-connected workers, because these don't count
850  * towards the MAX_BACKENDS limit elsewhere. For now, it doesn't seem
851  * important to relax this restriction.
852  */
853  if (++numworkers > max_worker_processes)
854  {
855  ereport(LOG,
856  (errcode(ERRCODE_CONFIGURATION_LIMIT_EXCEEDED),
857  errmsg("too many background workers"),
858  errdetail_plural("Up to %d background worker can be registered with the current settings.",
859  "Up to %d background workers can be registered with the current settings.",
862  errhint("Consider increasing the configuration parameter \"max_worker_processes\".")));
863  return;
864  }
865 
866  /*
867  * Copy the registration data into the registered workers list.
868  */
869  rw = malloc(sizeof(RegisteredBgWorker));
870  if (rw == NULL)
871  {
872  ereport(LOG,
873  (errcode(ERRCODE_OUT_OF_MEMORY),
874  errmsg("out of memory")));
875  return;
876  }
877 
878  rw->rw_worker = *worker;
879  rw->rw_backend = NULL;
880  rw->rw_pid = 0;
881  rw->rw_child_slot = 0;
882  rw->rw_crashed_at = 0;
883  rw->rw_terminate = false;
884 
885  slist_push_head(&BackgroundWorkerList, &rw->rw_lnode);
886 }
887 
888 /*
889  * Register a new background worker from a regular backend.
890  *
891  * Returns true on success and false on failure. Failure typically indicates
892  * that no background worker slots are currently available.
893  *
894  * If handle != NULL, we'll set *handle to a pointer that can subsequently
895  * be used as an argument to GetBackgroundWorkerPid(). The caller can
896  * free this pointer using pfree(), if desired.
897  */
898 bool
900  BackgroundWorkerHandle **handle)
901 {
902  int slotno;
903  bool success = false;
904  bool parallel;
905  uint64 generation = 0;
906 
907  /*
908  * We can't register dynamic background workers from the postmaster. If
909  * this is a standalone backend, we're the only process and can't start
910  * any more. In a multi-process environment, it might be theoretically
911  * possible, but we don't currently support it due to locking
912  * considerations; see comments on the BackgroundWorkerSlot data
913  * structure.
914  */
915  if (!IsUnderPostmaster)
916  return false;
917 
918  if (!SanityCheckBackgroundWorker(worker, ERROR))
919  return false;
920 
921  parallel = (worker->bgw_flags & BGWORKER_CLASS_PARALLEL) != 0;
922 
923  LWLockAcquire(BackgroundWorkerLock, LW_EXCLUSIVE);
924 
925  /*
926  * If this is a parallel worker, check whether there are already too many
927  * parallel workers; if so, don't register another one. Our view of
928  * parallel_terminate_count may be slightly stale, but that doesn't really
929  * matter: we would have gotten the same result if we'd arrived here
930  * slightly earlier anyway. There's no help for it, either, since the
931  * postmaster must not take locks; a memory barrier wouldn't guarantee
932  * anything useful.
933  */
934  if (parallel && (BackgroundWorkerData->parallel_register_count -
935  BackgroundWorkerData->parallel_terminate_count) >=
937  {
938  LWLockRelease(BackgroundWorkerLock);
939  return false;
940  }
941 
942  /*
943  * Look for an unused slot. If we find one, grab it.
944  */
945  for (slotno = 0; slotno < BackgroundWorkerData->total_slots; ++slotno)
946  {
947  BackgroundWorkerSlot *slot = &BackgroundWorkerData->slot[slotno];
948 
949  if (!slot->in_use)
950  {
951  memcpy(&slot->worker, worker, sizeof(BackgroundWorker));
952  slot->pid = InvalidPid; /* indicates not started yet */
953  slot->generation++;
954  slot->terminate = false;
955  generation = slot->generation;
956  if (parallel)
957  BackgroundWorkerData->parallel_register_count++;
958 
959  /*
960  * Make sure postmaster doesn't see the slot as in use before it
961  * sees the new contents.
962  */
964 
965  slot->in_use = true;
966  success = true;
967  break;
968  }
969  }
970 
971  LWLockRelease(BackgroundWorkerLock);
972 
973  /* If we found a slot, tell the postmaster to notice the change. */
974  if (success)
976 
977  /*
978  * If we found a slot and the user has provided a handle, initialize it.
979  */
980  if (success && handle)
981  {
982  *handle = palloc(sizeof(BackgroundWorkerHandle));
983  (*handle)->slot = slotno;
984  (*handle)->generation = generation;
985  }
986 
987  return success;
988 }
989 
990 /*
991  * Get the PID of a dynamically-registered background worker.
992  *
993  * If the worker is determined to be running, the return value will be
994  * BGWH_STARTED and *pidp will get the PID of the worker process.
995  * Otherwise, the return value will be BGWH_NOT_YET_STARTED if the worker
996  * hasn't been started yet, and BGWH_STOPPED if the worker was previously
997  * running but is no longer.
998  *
999  * In the latter case, the worker may be stopped temporarily (if it is
1000  * configured for automatic restart and exited non-zero) or gone for
1001  * good (if it exited with code 0 or if it is configured not to restart).
1002  */
1005 {
1006  BackgroundWorkerSlot *slot;
1007  pid_t pid;
1008 
1009  Assert(handle->slot < max_worker_processes);
1010  slot = &BackgroundWorkerData->slot[handle->slot];
1011 
1012  /*
1013  * We could probably arrange to synchronize access to data using memory
1014  * barriers only, but for now, let's just keep it simple and grab the
1015  * lock. It seems unlikely that there will be enough traffic here to
1016  * result in meaningful contention.
1017  */
1018  LWLockAcquire(BackgroundWorkerLock, LW_SHARED);
1019 
1020  /*
1021  * The generation number can't be concurrently changed while we hold the
1022  * lock. The pid, which is updated by the postmaster, can change at any
1023  * time, but we assume such changes are atomic. So the value we read
1024  * won't be garbage, but it might be out of date by the time the caller
1025  * examines it (but that's unavoidable anyway).
1026  */
1027  if (handle->generation != slot->generation)
1028  pid = 0;
1029  else
1030  pid = slot->pid;
1031 
1032  /* All done. */
1033  LWLockRelease(BackgroundWorkerLock);
1034 
1035  if (pid == 0)
1036  return BGWH_STOPPED;
1037  else if (pid == InvalidPid)
1038  return BGWH_NOT_YET_STARTED;
1039  *pidp = pid;
1040  return BGWH_STARTED;
1041 }
1042 
1043 /*
1044  * Wait for a background worker to start up.
1045  *
1046  * This is like GetBackgroundWorkerPid(), except that if the worker has not
1047  * yet started, we wait for it to do so; thus, BGWH_NOT_YET_STARTED is never
1048  * returned. However, if the postmaster has died, we give up and return
1049  * BGWH_POSTMASTER_DIED, since it that case we know that startup will not
1050  * take place.
1051  */
1054 {
1056  int rc;
1057 
1058  for (;;)
1059  {
1060  pid_t pid;
1061 
1063 
1064  status = GetBackgroundWorkerPid(handle, &pid);
1065  if (status == BGWH_STARTED)
1066  *pidp = pid;
1067  if (status != BGWH_NOT_YET_STARTED)
1068  break;
1069 
1070  rc = WaitLatch(MyLatch,
1073 
1074  if (rc & WL_POSTMASTER_DEATH)
1075  {
1076  status = BGWH_POSTMASTER_DIED;
1077  break;
1078  }
1079 
1081  }
1082 
1083  return status;
1084 }
1085 
1086 /*
1087  * Wait for a background worker to stop.
1088  *
1089  * If the worker hasn't yet started, or is running, we wait for it to stop
1090  * and then return BGWH_STOPPED. However, if the postmaster has died, we give
1091  * up and return BGWH_POSTMASTER_DIED, because it's the postmaster that
1092  * notifies us when a worker's state changes.
1093  */
1096 {
1098  int rc;
1099 
1100  for (;;)
1101  {
1102  pid_t pid;
1103 
1105 
1106  status = GetBackgroundWorkerPid(handle, &pid);
1107  if (status == BGWH_STOPPED)
1108  break;
1109 
1110  rc = WaitLatch(&MyProc->procLatch,
1113 
1114  if (rc & WL_POSTMASTER_DEATH)
1115  {
1116  status = BGWH_POSTMASTER_DIED;
1117  break;
1118  }
1119 
1121  }
1122 
1123  return status;
1124 }
1125 
1126 /*
1127  * Instruct the postmaster to terminate a background worker.
1128  *
1129  * Note that it's safe to do this without regard to whether the worker is
1130  * still running, or even if the worker may already have existed and been
1131  * unregistered.
1132  */
1133 void
1135 {
1136  BackgroundWorkerSlot *slot;
1137  bool signal_postmaster = false;
1138 
1139  Assert(handle->slot < max_worker_processes);
1140  slot = &BackgroundWorkerData->slot[handle->slot];
1141 
1142  /* Set terminate flag in shared memory, unless slot has been reused. */
1143  LWLockAcquire(BackgroundWorkerLock, LW_EXCLUSIVE);
1144  if (handle->generation == slot->generation)
1145  {
1146  slot->terminate = true;
1147  signal_postmaster = true;
1148  }
1149  LWLockRelease(BackgroundWorkerLock);
1150 
1151  /* Make sure the postmaster notices the change to shared memory. */
1152  if (signal_postmaster)
1154 }
char bgw_extra[BGW_EXTRALEN]
Definition: bgworker.h:98
void InitializeTimeouts(void)
Definition: timeout.c:340
static void bgworker_sigusr1_handler(SIGNAL_ARGS)
Definition: bgworker.c:630
struct bkend * rw_backend
int max_parallel_workers
Definition: globals.c:125
BgwHandleStatus WaitForBackgroundWorkerStartup(BackgroundWorkerHandle *handle, pid_t *pidp)
Definition: bgworker.c:1053
#define SIGUSR1
Definition: win32.h:211
void RegisterBackgroundWorker(BackgroundWorker *worker)
Definition: bgworker.c:805
#define DEBUG1
Definition: elog.h:25
int errhint(const char *fmt,...)
Definition: elog.c:987
void BackgroundWorkerStateChange(void)
Definition: bgworker.c:222
void ApplyLauncherMain(Datum main_arg)
Definition: launcher.c:632
bool process_shared_preload_libraries_in_progress
Definition: miscinit.c:1417
slist_node * cur
Definition: ilist.h:226
PGPROC * MyProc
Definition: proc.c:67
static BackgroundWorkerArray * BackgroundWorkerData
Definition: bgworker.c:109
slist_node * cur
Definition: ilist.h:241
static void slist_push_head(slist_head *head, slist_node *node)
Definition: ilist.h:574
void ReportBackgroundWorkerExit(slist_mutable_iter *cur)
Definition: bgworker.c:439
int bgw_restart_time
Definition: bgworker.h:93
struct cursor * cur
Definition: ecpg.c:28
void proc_exit(int code)
Definition: ipc.c:99
int errcode(int sqlerrcode)
Definition: elog.c:575
#define BGWORKER_CLASS_PARALLEL
Definition: bgworker.h:67
#define SetProcessingMode(mode)
Definition: miscadmin.h:371
BackgroundWorker * MyBgworkerEntry
Definition: postmaster.c:189
void BaseInit(void)
Definition: postinit.c:517
int snprintf(char *str, size_t count, const char *fmt,...) pg_attribute_printf(3
void ascii_safe_strlcpy(char *dest, const char *src, size_t destsiz)
Definition: ascii.c:173
void ResetLatch(volatile Latch *latch)
Definition: latch.c:461
#define LOG
Definition: elog.h:26
#define BGWORKER_SHMEM_ACCESS
Definition: bgworker.h:52
void BackgroundWorkerStopNotifications(pid_t pid)
Definition: bgworker.c:473
void ResetBackgroundWorkerCrashTimes(void)
Definition: bgworker.c:495
static const bgworker_main_type InternalBGWorkers[]
Definition: bgworker.c:115
char bgw_function_name[BGW_MAXLEN]
Definition: bgworker.h:96
#define SIGQUIT
Definition: win32.h:197
Size BackgroundWorkerShmemSize(void)
Definition: bgworker.c:124
void PGSharedMemoryDetach(void)
Definition: sysv_shmem.c:768
#define PG_SETMASK(mask)
Definition: pqsignal.h:19
void StatementCancelHandler(SIGNAL_ARGS)
Definition: postgres.c:2650
Latch procLatch
Definition: proc.h:103
bool IsBackgroundWorker
Definition: globals.c:102
void StartBackgroundWorker(void)
Definition: bgworker.c:646
#define slist_foreach_modify(iter, lhead)
Definition: ilist.h:716
#define malloc(a)
Definition: header.h:50
void LWLockRelease(LWLock *lock)
Definition: lwlock.c:1715
ErrorContextCallback * error_context_stack
Definition: elog.c:88
void pg_usleep(long microsec)
Definition: signal.c:53
Datum bgw_main_arg
Definition: bgworker.h:97
int WaitLatch(volatile Latch *latch, int wakeEvents, long timeout, uint32 wait_event_info)
Definition: latch.c:300
#define SIG_IGN
Definition: win32.h:193
void BackgroundWorkerShmemInit(void)
Definition: bgworker.c:140
void ReportBackgroundWorkerPID(RegisteredBgWorker *rw)
Definition: bgworker.c:420
#define ERROR
Definition: elog.h:43
BgwHandleStatus WaitForBackgroundWorkerShutdown(BackgroundWorkerHandle *handle)
Definition: bgworker.c:1095
#define SLIST_STATIC_INIT(name)
Definition: ilist.h:249
struct BackgroundWorkerSlot BackgroundWorkerSlot
void on_exit_reset(void)
Definition: ipc.c:396
void * ShmemInitStruct(const char *name, Size size, bool *foundPtr)
Definition: shmem.c:372
#define FATAL
Definition: elog.h:52
void(* bgworker_main_type)(Datum main_arg)
Definition: bgworker.h:71
bgworker_main_type bgw_main
Definition: bgworker.h:94
#define MAXPGPATH
bool PostmasterMarkPIDForWorkerNotify(int pid)
Definition: postmaster.c:5788
slist_head BackgroundWorkerList
Definition: bgworker.c:41
void InitProcess(void)
Definition: proc.c:287
static bool success
Definition: pg_basebackup.c:96
uint32 parallel_register_count
Definition: bgworker.c:98
static char * buf
Definition: pg_test_fsync.c:65
bool IsUnderPostmaster
Definition: globals.c:100
void ForgetBackgroundWorker(slist_mutable_iter *cur)
Definition: bgworker.c:392
#define BGW_NEVER_RESTART
Definition: bgworker.h:84
unsigned int uint32
Definition: c.h:268
BgwHandleStatus
Definition: bgworker.h:102
#define USECS_PER_DAY
Definition: timestamp.h:91
#define ereport(elevel, rest)
Definition: elog.h:122
static bool SanityCheckBackgroundWorker(BackgroundWorker *worker, int elevel)
Definition: bgworker.c:542
PGFunction load_external_function(char *filename, char *funcname, bool signalNotFound, void **filehandle)
Definition: dfmgr.c:94
static int elevel
Definition: vacuumlazy.c:137
Size mul_size(Size s1, Size s2)
Definition: shmem.c:492
#define slist_container(type, membername, ptr)
Definition: ilist.h:674
sigset_t BlockSig
Definition: pqsignal.c:22
#define WL_POSTMASTER_DEATH
Definition: latch.h:128
struct BackgroundWorkerArray BackgroundWorkerArray
Size add_size(Size s1, Size s2)
Definition: shmem.c:475
int PostAuthDelay
Definition: postgres.c:97
void EmitErrorReport(void)
Definition: elog.c:1446
static RegisteredBgWorker * FindRegisteredWorkerBySlotNumber(int slotno)
Definition: bgworker.c:199
#define SIGPIPE
Definition: win32.h:201
#define SIGHUP
Definition: win32.h:196
void TerminateBackgroundWorker(BackgroundWorkerHandle *handle)
Definition: bgworker.c:1134
#define SIG_DFL
Definition: win32.h:191
pqsigfunc pqsignal(int signum, pqsigfunc handler)
Definition: signal.c:168
#define free(a)
Definition: header.h:65
#define pg_memory_barrier()
Definition: atomics.h:147
#define SIGNAL_ARGS
Definition: c.h:1079
#define NULL
Definition: c.h:229
char bgw_name[BGW_MAXLEN]
Definition: bgworker.h:90
#define Assert(condition)
Definition: c.h:675
BackgroundWorker worker
Definition: bgworker.c:81
#define BGWORKER_BACKEND_DATABASE_CONNECTION
Definition: bgworker.h:59
#define pg_read_barrier()
Definition: atomics.h:160
#define BGW_MAXLEN
Definition: bgworker.h:85
size_t Size
Definition: c.h:356
BgWorkerStartTime bgw_start_time
Definition: bgworker.h:92
int errdetail_plural(const char *fmt_singular, const char *fmt_plural, unsigned long n,...)
Definition: elog.c:965
bool RegisterDynamicBackgroundWorker(BackgroundWorker *worker, BackgroundWorkerHandle **handle)
Definition: bgworker.c:899
bool LWLockAcquire(LWLock *lock, LWLockMode mode)
Definition: lwlock.c:1111
void dsm_detach_all(void)
Definition: dsm.c:654
sigjmp_buf * PG_exception_stack
Definition: elog.c:90
#define slist_foreach(iter, lhead)
Definition: ilist.h:700
void * palloc(Size size)
Definition: mcxt.c:849
int errmsg(const char *fmt,...)
Definition: elog.c:797
uint32 parallel_terminate_count
Definition: bgworker.c:99
pid_t bgw_notify_pid
Definition: bgworker.h:99
#define HOLD_INTERRUPTS()
Definition: miscadmin.h:114
int i
void FloatExceptionHandler(SIGNAL_ARGS)
Definition: postgres.c:2671
#define pg_write_barrier()
Definition: atomics.h:161
int max_worker_processes
Definition: globals.c:124
struct Latch * MyLatch
Definition: globals.c:51
static void bgworker_die(SIGNAL_ARGS)
Definition: bgworker.c:613
#define CHECK_FOR_INTERRUPTS()
Definition: miscadmin.h:97
static void slist_delete_current(slist_mutable_iter *iter)
Definition: ilist.h:652
void SendPostmasterSignal(PMSignalReason reason)
Definition: pmsignal.c:113
#define elog
Definition: elog.h:219
static void bgworker_quickdie(SIGNAL_ARGS)
Definition: bgworker.c:583
void latch_sigusr1_handler(void)
Definition: latch.c:1572
void procsignal_sigusr1_handler(SIGNAL_ARGS)
Definition: procsignal.c:260
static void static void status(const char *fmt,...) pg_attribute_printf(1
Definition: pg_regress.c:224
BackgroundWorker rw_worker
#define SIGCHLD
Definition: win32.h:206
BackgroundWorkerSlot slot[FLEXIBLE_ARRAY_MEMBER]
Definition: bgworker.c:100
char bgw_library_name[BGW_MAXLEN]
Definition: bgworker.h:95
#define BGW_EXTRALEN
Definition: bgworker.h:86
#define WL_LATCH_SET
Definition: latch.h:124
#define SIGUSR2
Definition: win32.h:212
#define offsetof(type, field)
Definition: c.h:555
BgwHandleStatus GetBackgroundWorkerPid(BackgroundWorkerHandle *handle, pid_t *pidp)
Definition: bgworker.c:1004
void init_ps_display(const char *username, const char *dbname, const char *host_info, const char *initial_str)
Definition: ps_status.c:244
#define InvalidPid
Definition: miscadmin.h:31