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  * Cancel SIGUSR1 notifications for a PID belonging to an exiting backend.
434  *
435  * This function should only be called from the postmaster.
436  */
437 void
439 {
440  slist_iter siter;
441 
442  slist_foreach(siter, &BackgroundWorkerList)
443  {
444  RegisteredBgWorker *rw;
445 
446  rw = slist_container(RegisteredBgWorker, rw_lnode, siter.cur);
447  if (rw->rw_worker.bgw_notify_pid == pid)
448  rw->rw_worker.bgw_notify_pid = 0;
449  }
450 }
451 
452 /*
453  * Reset background worker crash state.
454  *
455  * We assume that, after a crash-and-restart cycle, background workers without
456  * the never-restart flag should be restarted immediately, instead of waiting
457  * for bgw_restart_time to elapse.
458  */
459 void
461 {
462  slist_mutable_iter iter;
463 
464  slist_foreach_modify(iter, &BackgroundWorkerList)
465  {
466  RegisteredBgWorker *rw;
467 
468  rw = slist_container(RegisteredBgWorker, rw_lnode, iter.cur);
469 
470  /*
471  * For workers that should not be restarted, we don't want to lose the
472  * information that they have crashed; otherwise, they would be
473  * restarted, which is wrong.
474  */
476  rw->rw_crashed_at = 0;
477  }
478 }
479 
480 #ifdef EXEC_BACKEND
481 /*
482  * In EXEC_BACKEND mode, workers use this to retrieve their details from
483  * shared memory.
484  */
486 BackgroundWorkerEntry(int slotno)
487 {
488  static BackgroundWorker myEntry;
489  BackgroundWorkerSlot *slot;
490 
491  Assert(slotno < BackgroundWorkerData->total_slots);
492  slot = &BackgroundWorkerData->slot[slotno];
493  Assert(slot->in_use);
494 
495  /* must copy this in case we don't intend to retain shmem access */
496  memcpy(&myEntry, &slot->worker, sizeof myEntry);
497  return &myEntry;
498 }
499 #endif
500 
501 /*
502  * Complain about the BackgroundWorker definition using error level elevel.
503  * Return true if it looks ok, false if not (unless elevel >= ERROR, in
504  * which case we won't return at all in the not-OK case).
505  */
506 static bool
508 {
509  /* sanity check for flags */
511  {
512  if (!(worker->bgw_flags & BGWORKER_SHMEM_ACCESS))
513  {
514  ereport(elevel,
515  (errcode(ERRCODE_INVALID_PARAMETER_VALUE),
516  errmsg("background worker \"%s\": must attach to shared memory in order to request a database connection",
517  worker->bgw_name)));
518  return false;
519  }
520 
522  {
523  ereport(elevel,
524  (errcode(ERRCODE_INVALID_PARAMETER_VALUE),
525  errmsg("background worker \"%s\": cannot request database access if starting at postmaster start",
526  worker->bgw_name)));
527  return false;
528  }
529 
530  /* XXX other checks? */
531  }
532 
533  if ((worker->bgw_restart_time < 0 &&
534  worker->bgw_restart_time != BGW_NEVER_RESTART) ||
535  (worker->bgw_restart_time > USECS_PER_DAY / 1000))
536  {
537  ereport(elevel,
538  (errcode(ERRCODE_INVALID_PARAMETER_VALUE),
539  errmsg("background worker \"%s\": invalid restart interval",
540  worker->bgw_name)));
541  return false;
542  }
543 
544  return true;
545 }
546 
547 static void
549 {
550  sigaddset(&BlockSig, SIGQUIT); /* prevent nested calls */
552 
553  /*
554  * We DO NOT want to run proc_exit() callbacks -- we're here because
555  * shared memory may be corrupted, so we don't want to try to clean up our
556  * transaction. Just nail the windows shut and get out of town. Now that
557  * there's an atexit callback to prevent third-party code from breaking
558  * things by calling exit() directly, we have to reset the callbacks
559  * explicitly to make this work as intended.
560  */
561  on_exit_reset();
562 
563  /*
564  * Note we do exit(2) not exit(0). This is to force the postmaster into a
565  * system reset cycle if some idiot DBA sends a manual SIGQUIT to a random
566  * backend. This is necessary precisely because we don't clean up our
567  * shared memory state. (The "dead man switch" mechanism in pmsignal.c
568  * should ensure the postmaster sees this as a crash, too, but no harm in
569  * being doubly sure.)
570  */
571  exit(2);
572 }
573 
574 /*
575  * Standard SIGTERM handler for background workers
576  */
577 static void
579 {
581 
582  ereport(FATAL,
583  (errcode(ERRCODE_ADMIN_SHUTDOWN),
584  errmsg("terminating background worker \"%s\" due to administrator command",
586 }
587 
588 /*
589  * Standard SIGUSR1 handler for unconnected workers
590  *
591  * Here, we want to make sure an unconnected worker will at least heed
592  * latch activity.
593  */
594 static void
596 {
597  int save_errno = errno;
598 
600 
601  errno = save_errno;
602 }
603 
604 /*
605  * Start a new background worker
606  *
607  * This is the main entry point for background worker, to be called from
608  * postmaster.
609  */
610 void
612 {
613  sigjmp_buf local_sigjmp_buf;
614  char buf[MAXPGPATH];
616  bgworker_main_type entrypt;
617 
618  if (worker == NULL)
619  elog(FATAL, "unable to find bgworker entry");
620 
621  IsBackgroundWorker = true;
622 
623  /* Identify myself via ps */
624  snprintf(buf, MAXPGPATH, "bgworker: %s", worker->bgw_name);
625  init_ps_display(buf, "", "", "");
626 
627  /*
628  * If we're not supposed to have shared memory access, then detach from
629  * shared memory. If we didn't request shared memory access, the
630  * postmaster won't force a cluster-wide restart if we exit unexpectedly,
631  * so we'd better make sure that we don't mess anything up that would
632  * require that sort of cleanup.
633  */
634  if ((worker->bgw_flags & BGWORKER_SHMEM_ACCESS) == 0)
635  {
636  dsm_detach_all();
638  }
639 
641 
642  /* Apply PostAuthDelay */
643  if (PostAuthDelay > 0)
644  pg_usleep(PostAuthDelay * 1000000L);
645 
646  /*
647  * Set up signal handlers.
648  */
650  {
651  /*
652  * SIGINT is used to signal canceling the current action
653  */
657 
658  /* XXX Any other handlers needed here? */
659  }
660  else
661  {
662  pqsignal(SIGINT, SIG_IGN);
664  pqsignal(SIGFPE, SIG_IGN);
665  }
666  pqsignal(SIGTERM, bgworker_die);
668 
670  InitializeTimeouts(); /* establishes SIGALRM handler */
671 
675 
676  /*
677  * If an exception is encountered, processing resumes here.
678  *
679  * See notes in postgres.c about the design of this coding.
680  */
681  if (sigsetjmp(local_sigjmp_buf, 1) != 0)
682  {
683  /* Since not using PG_TRY, must reset error stack by hand */
685 
686  /* Prevent interrupts while cleaning up */
687  HOLD_INTERRUPTS();
688 
689  /* Report the error to the server log */
690  EmitErrorReport();
691 
692  /*
693  * Do we need more cleanup here? For shmem-connected bgworkers, we
694  * will call InitProcess below, which will install ProcKill as exit
695  * callback. That will take care of releasing locks, etc.
696  */
697 
698  /* and go away */
699  proc_exit(1);
700  }
701 
702  /* We can now handle ereport(ERROR) */
703  PG_exception_stack = &local_sigjmp_buf;
704 
705  /*
706  * If the background worker request shared memory access, set that up now;
707  * else, detach all shared memory segments.
708  */
709  if (worker->bgw_flags & BGWORKER_SHMEM_ACCESS)
710  {
711  /*
712  * Early initialization. Some of this could be useful even for
713  * background workers that aren't using shared memory, but they can
714  * call the individual startup routines for those subsystems if
715  * needed.
716  */
717  BaseInit();
718 
719  /*
720  * Create a per-backend PGPROC struct in shared memory, except in the
721  * EXEC_BACKEND case where this was done in SubPostmasterMain. We must
722  * do this before we can use LWLocks (and in the EXEC_BACKEND case we
723  * already had to do some stuff with LWLocks).
724  */
725 #ifndef EXEC_BACKEND
726  InitProcess();
727 #endif
728  }
729 
730  /*
731  * If bgw_main is set, we use that value as the initial entrypoint.
732  * However, if the library containing the entrypoint wasn't loaded at
733  * postmaster startup time, passing it as a direct function pointer is not
734  * possible. To work around that, we allow callers for whom a function
735  * pointer is not available to pass a library name (which will be loaded,
736  * if necessary) and a function name (which will be looked up in the named
737  * library).
738  */
739  if (worker->bgw_main != NULL)
740  entrypt = worker->bgw_main;
741  else
742  entrypt = (bgworker_main_type)
744  worker->bgw_function_name,
745  true, NULL);
746 
747  /*
748  * Note that in normal processes, we would call InitPostgres here. For a
749  * worker, however, we don't know what database to connect to, yet; so we
750  * need to wait until the user code does it via
751  * BackgroundWorkerInitializeConnection().
752  */
753 
754  /*
755  * Now invoke the user-defined worker code
756  */
757  entrypt(worker->bgw_main_arg);
758 
759  /* ... and if it returns, we're done */
760  proc_exit(0);
761 }
762 
763 /*
764  * Register a new background worker while processing shared_preload_libraries.
765  *
766  * This can only be called in the _PG_init function of a module library
767  * that's loaded by shared_preload_libraries; otherwise it has no effect.
768  */
769 void
771 {
772  RegisteredBgWorker *rw;
773  static int numworkers = 0;
774  bool internal = false;
775  int i;
776 
777  if (!IsUnderPostmaster)
778  ereport(DEBUG1,
779  (errmsg("registering background worker \"%s\"", worker->bgw_name)));
780 
781  for (i = 0; InternalBGWorkers[i]; i++)
782  {
783  if (worker->bgw_main == InternalBGWorkers[i])
784  {
785  internal = true;
786  break;
787  }
788  }
789 
791  {
792  if (!IsUnderPostmaster)
793  ereport(LOG,
794  (errcode(ERRCODE_FEATURE_NOT_SUPPORTED),
795  errmsg("background worker \"%s\": must be registered in shared_preload_libraries",
796  worker->bgw_name)));
797  return;
798  }
799 
800  if (!SanityCheckBackgroundWorker(worker, LOG))
801  return;
802 
803  if (worker->bgw_notify_pid != 0)
804  {
805  ereport(LOG,
806  (errcode(ERRCODE_FEATURE_NOT_SUPPORTED),
807  errmsg("background worker \"%s\": only dynamic background workers can request notification",
808  worker->bgw_name)));
809  return;
810  }
811 
812  /*
813  * Enforce maximum number of workers. Note this is overly restrictive: we
814  * could allow more non-shmem-connected workers, because these don't count
815  * towards the MAX_BACKENDS limit elsewhere. For now, it doesn't seem
816  * important to relax this restriction.
817  */
818  if (++numworkers > max_worker_processes)
819  {
820  ereport(LOG,
821  (errcode(ERRCODE_CONFIGURATION_LIMIT_EXCEEDED),
822  errmsg("too many background workers"),
823  errdetail_plural("Up to %d background worker can be registered with the current settings.",
824  "Up to %d background workers can be registered with the current settings.",
827  errhint("Consider increasing the configuration parameter \"max_worker_processes\".")));
828  return;
829  }
830 
831  /*
832  * Copy the registration data into the registered workers list.
833  */
834  rw = malloc(sizeof(RegisteredBgWorker));
835  if (rw == NULL)
836  {
837  ereport(LOG,
838  (errcode(ERRCODE_OUT_OF_MEMORY),
839  errmsg("out of memory")));
840  return;
841  }
842 
843  rw->rw_worker = *worker;
844  rw->rw_backend = NULL;
845  rw->rw_pid = 0;
846  rw->rw_child_slot = 0;
847  rw->rw_crashed_at = 0;
848  rw->rw_terminate = false;
849 
850  slist_push_head(&BackgroundWorkerList, &rw->rw_lnode);
851 }
852 
853 /*
854  * Register a new background worker from a regular backend.
855  *
856  * Returns true on success and false on failure. Failure typically indicates
857  * that no background worker slots are currently available.
858  *
859  * If handle != NULL, we'll set *handle to a pointer that can subsequently
860  * be used as an argument to GetBackgroundWorkerPid(). The caller can
861  * free this pointer using pfree(), if desired.
862  */
863 bool
865  BackgroundWorkerHandle **handle)
866 {
867  int slotno;
868  bool success = false;
869  bool parallel;
870  uint64 generation = 0;
871 
872  /*
873  * We can't register dynamic background workers from the postmaster. If
874  * this is a standalone backend, we're the only process and can't start
875  * any more. In a multi-process environment, it might be theoretically
876  * possible, but we don't currently support it due to locking
877  * considerations; see comments on the BackgroundWorkerSlot data
878  * structure.
879  */
880  if (!IsUnderPostmaster)
881  return false;
882 
883  if (!SanityCheckBackgroundWorker(worker, ERROR))
884  return false;
885 
886  parallel = (worker->bgw_flags & BGWORKER_CLASS_PARALLEL) != 0;
887 
888  LWLockAcquire(BackgroundWorkerLock, LW_EXCLUSIVE);
889 
890  /*
891  * If this is a parallel worker, check whether there are already too many
892  * parallel workers; if so, don't register another one. Our view of
893  * parallel_terminate_count may be slightly stale, but that doesn't really
894  * matter: we would have gotten the same result if we'd arrived here
895  * slightly earlier anyway. There's no help for it, either, since the
896  * postmaster must not take locks; a memory barrier wouldn't guarantee
897  * anything useful.
898  */
899  if (parallel && (BackgroundWorkerData->parallel_register_count -
900  BackgroundWorkerData->parallel_terminate_count) >=
902  {
903  LWLockRelease(BackgroundWorkerLock);
904  return false;
905  }
906 
907  /*
908  * Look for an unused slot. If we find one, grab it.
909  */
910  for (slotno = 0; slotno < BackgroundWorkerData->total_slots; ++slotno)
911  {
912  BackgroundWorkerSlot *slot = &BackgroundWorkerData->slot[slotno];
913 
914  if (!slot->in_use)
915  {
916  memcpy(&slot->worker, worker, sizeof(BackgroundWorker));
917  slot->pid = InvalidPid; /* indicates not started yet */
918  slot->generation++;
919  slot->terminate = false;
920  generation = slot->generation;
921  if (parallel)
922  BackgroundWorkerData->parallel_register_count++;
923 
924  /*
925  * Make sure postmaster doesn't see the slot as in use before it
926  * sees the new contents.
927  */
929 
930  slot->in_use = true;
931  success = true;
932  break;
933  }
934  }
935 
936  LWLockRelease(BackgroundWorkerLock);
937 
938  /* If we found a slot, tell the postmaster to notice the change. */
939  if (success)
941 
942  /*
943  * If we found a slot and the user has provided a handle, initialize it.
944  */
945  if (success && handle)
946  {
947  *handle = palloc(sizeof(BackgroundWorkerHandle));
948  (*handle)->slot = slotno;
949  (*handle)->generation = generation;
950  }
951 
952  return success;
953 }
954 
955 /*
956  * Get the PID of a dynamically-registered background worker.
957  *
958  * If the worker is determined to be running, the return value will be
959  * BGWH_STARTED and *pidp will get the PID of the worker process.
960  * Otherwise, the return value will be BGWH_NOT_YET_STARTED if the worker
961  * hasn't been started yet, and BGWH_STOPPED if the worker was previously
962  * running but is no longer.
963  *
964  * In the latter case, the worker may be stopped temporarily (if it is
965  * configured for automatic restart and exited non-zero) or gone for
966  * good (if it exited with code 0 or if it is configured not to restart).
967  */
970 {
971  BackgroundWorkerSlot *slot;
972  pid_t pid;
973 
974  Assert(handle->slot < max_worker_processes);
975  slot = &BackgroundWorkerData->slot[handle->slot];
976 
977  /*
978  * We could probably arrange to synchronize access to data using memory
979  * barriers only, but for now, let's just keep it simple and grab the
980  * lock. It seems unlikely that there will be enough traffic here to
981  * result in meaningful contention.
982  */
983  LWLockAcquire(BackgroundWorkerLock, LW_SHARED);
984 
985  /*
986  * The generation number can't be concurrently changed while we hold the
987  * lock. The pid, which is updated by the postmaster, can change at any
988  * time, but we assume such changes are atomic. So the value we read
989  * won't be garbage, but it might be out of date by the time the caller
990  * examines it (but that's unavoidable anyway).
991  */
992  if (handle->generation != slot->generation)
993  pid = 0;
994  else
995  pid = slot->pid;
996 
997  /* All done. */
998  LWLockRelease(BackgroundWorkerLock);
999 
1000  if (pid == 0)
1001  return BGWH_STOPPED;
1002  else if (pid == InvalidPid)
1003  return BGWH_NOT_YET_STARTED;
1004  *pidp = pid;
1005  return BGWH_STARTED;
1006 }
1007 
1008 /*
1009  * Wait for a background worker to start up.
1010  *
1011  * This is like GetBackgroundWorkerPid(), except that if the worker has not
1012  * yet started, we wait for it to do so; thus, BGWH_NOT_YET_STARTED is never
1013  * returned. However, if the postmaster has died, we give up and return
1014  * BGWH_POSTMASTER_DIED, since it that case we know that startup will not
1015  * take place.
1016  */
1019 {
1021  int rc;
1022 
1023  for (;;)
1024  {
1025  pid_t pid;
1026 
1028 
1029  status = GetBackgroundWorkerPid(handle, &pid);
1030  if (status == BGWH_STARTED)
1031  *pidp = pid;
1032  if (status != BGWH_NOT_YET_STARTED)
1033  break;
1034 
1035  rc = WaitLatch(MyLatch,
1038 
1039  if (rc & WL_POSTMASTER_DEATH)
1040  {
1041  status = BGWH_POSTMASTER_DIED;
1042  break;
1043  }
1044 
1046  }
1047 
1048  return status;
1049 }
1050 
1051 /*
1052  * Wait for a background worker to stop.
1053  *
1054  * If the worker hasn't yet started, or is running, we wait for it to stop
1055  * and then return BGWH_STOPPED. However, if the postmaster has died, we give
1056  * up and return BGWH_POSTMASTER_DIED, because it's the postmaster that
1057  * notifies us when a worker's state changes.
1058  */
1061 {
1063  int rc;
1064 
1065  for (;;)
1066  {
1067  pid_t pid;
1068 
1070 
1071  status = GetBackgroundWorkerPid(handle, &pid);
1072  if (status == BGWH_STOPPED)
1073  break;
1074 
1075  rc = WaitLatch(&MyProc->procLatch,
1078 
1079  if (rc & WL_POSTMASTER_DEATH)
1080  {
1081  status = BGWH_POSTMASTER_DIED;
1082  break;
1083  }
1084 
1086  }
1087 
1088  return status;
1089 }
1090 
1091 /*
1092  * Instruct the postmaster to terminate a background worker.
1093  *
1094  * Note that it's safe to do this without regard to whether the worker is
1095  * still running, or even if the worker may already have existed and been
1096  * unregistered.
1097  */
1098 void
1100 {
1101  BackgroundWorkerSlot *slot;
1102  bool signal_postmaster = false;
1103 
1104  Assert(handle->slot < max_worker_processes);
1105  slot = &BackgroundWorkerData->slot[handle->slot];
1106 
1107  /* Set terminate flag in shared memory, unless slot has been reused. */
1108  LWLockAcquire(BackgroundWorkerLock, LW_EXCLUSIVE);
1109  if (handle->generation == slot->generation)
1110  {
1111  slot->terminate = true;
1112  signal_postmaster = true;
1113  }
1114  LWLockRelease(BackgroundWorkerLock);
1115 
1116  /* Make sure the postmaster notices the change to shared memory. */
1117  if (signal_postmaster)
1119 }
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:595
struct bkend * rw_backend
int max_parallel_workers
Definition: globals.c:125
BgwHandleStatus WaitForBackgroundWorkerStartup(BackgroundWorkerHandle *handle, pid_t *pidp)
Definition: bgworker.c:1018
#define SIGUSR1
Definition: win32.h:211
void RegisterBackgroundWorker(BackgroundWorker *worker)
Definition: bgworker.c:770
#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:558
bool process_shared_preload_libraries_in_progress
Definition: miscinit.c:1401
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
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:462
#define LOG
Definition: elog.h:26
#define BGWORKER_SHMEM_ACCESS
Definition: bgworker.h:52
void BackgroundWorkerStopNotifications(pid_t pid)
Definition: bgworker.c:438
void ResetBackgroundWorkerCrashTimes(void)
Definition: bgworker.c:460
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:2648
Latch procLatch
Definition: proc.h:93
bool IsBackgroundWorker
Definition: globals.c:102
void StartBackgroundWorker(void)
Definition: bgworker.c:611
#define slist_foreach_modify(iter, lhead)
Definition: ilist.h:716
#define malloc(a)
Definition: header.h:45
void LWLockRelease(LWLock *lock)
Definition: lwlock.c:1714
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:301
#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:1060
#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:5781
slist_head BackgroundWorkerList
Definition: bgworker.c:41
void InitProcess(void)
Definition: proc.c:287
static bool success
Definition: pg_basebackup.c:99
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:265
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:507
PGFunction load_external_function(char *filename, char *funcname, bool signalNotFound, void **filehandle)
Definition: dfmgr.c:94
static int elevel
Definition: vacuumlazy.c:136
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:1099
#define SIG_DFL
Definition: win32.h:191
pqsigfunc pqsignal(int signum, pqsigfunc handler)
Definition: signal.c:168
#define free(a)
Definition: header.h:60
#define pg_memory_barrier()
Definition: atomics.h:147
#define SIGNAL_ARGS
Definition: c.h:1079
#define NULL
Definition: c.h:226
char bgw_name[BGW_MAXLEN]
Definition: bgworker.h:90
#define Assert(condition)
Definition: c.h:671
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:353
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:864
bool LWLockAcquire(LWLock *lock, LWLockMode mode)
Definition: lwlock.c:1110
void dsm_detach_all(void)
Definition: dsm.c:655
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:891
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:2669
#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:578
#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:548
void latch_sigusr1_handler(void)
Definition: latch.c:1541
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:222
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:551
BgwHandleStatus GetBackgroundWorkerPid(BackgroundWorkerHandle *handle, pid_t *pidp)
Definition: bgworker.c:969
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