Received: from malur.postgresql.org ([217.196.149.56]) by arkaria.postgresql.org with esmtp (Exim 4.80) (envelope-from ) id 1ZKWK2-00055b-5A for pgsql-docs@arkaria.postgresql.org; Wed, 29 Jul 2015 18:43:22 +0000 Received: from localhost ([127.0.0.1] helo=postgresql.org) by malur.postgresql.org with smtp (Exim 4.84) (envelope-from ) id 1ZKWK1-0008H2-NI for pgsql-docs@arkaria.postgresql.org; Wed, 29 Jul 2015 18:43:21 +0000 Received: from makus.postgresql.org ([2001:4800:1501:1::229]) by malur.postgresql.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_CBC_SHA384:256) (Exim 4.84) (envelope-from ) id 1ZKWJg-0007gf-Fc for pgsql-docs@postgresql.org; Wed, 29 Jul 2015 18:43:00 +0000 Received: from mail-vn0-x231.google.com ([2607:f8b0:400c:c0f::231]) by makus.postgresql.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_CBC_SHA1:256) (Exim 4.84) (envelope-from ) id 1ZKWJd-00028G-6H for pgsql-docs@postgresql.org; Wed, 29 Jul 2015 18:42:58 +0000 Received: by vnds125 with SMTP id s125so4311211vnd.1 for ; Wed, 29 Jul 2015 11:42:55 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20120113; h=mime-version:in-reply-to:references:date:message-id:subject:from:to :cc:content-type; bh=c/GpMXAaJBDmWP2US+DY9ukf4dRTY26EHp8NphUhO9M=; b=0OykSlhez3D/rpz0DQZzxe7yMmcXiLUaSpU3tLVb/cSpgadLm9haQR4EKUweJ2zNEX LXZYdCrJS+CCJ9BIb2BGS5LPmDdLmw8td/LE6SGoEtMYVyiN+hT0wH3t6n/dsujTZwDq VInxlRScFUrnku+jckNjGTOuTDam25TnMsCqXLXmfPEDwGgh3qxoIR0opAgGnEeiWYrW A56Na5QfrkkF2l9J7hBCC+qiJe3De5n2JUtlF2EMX43qQM0CtJ7jLkSm6O6IY8c+7If6 7KigwJdQwUNfO7bLinFOfZiCF/m6TZesX0JUXH6peIJBw5AzhD3B+l/zgKxwF5llLaXA i2xA== MIME-Version: 1.0 X-Received: by 10.52.104.7 with SMTP id ga7mr54235233vdb.16.1438195375437; Wed, 29 Jul 2015 11:42:55 -0700 (PDT) Received: by 10.31.1.215 with HTTP; Wed, 29 Jul 2015 11:42:55 -0700 (PDT) In-Reply-To: References:

Date: Wed, 29 Jul 2015 14:42:55 -0400 Message-ID: Subject: Re: bgworker / SPI docs patches From: Robert Haas To: Craig Ringer Cc: pgsql-docs Content-Type: text/plain; charset=UTF-8 X-Pg-Spam-Score: -2.7 (--) List-Archive: List-Help: List-ID: List-Owner: List-Post: List-Subscribe: List-Unsubscribe: X-Mailing-List: pgsql-docs Precedence: bulk Sender: pgsql-docs-owner@postgresql.org On Wed, Jul 29, 2015 at 11:35 AM, Robert Haas wrote: > On Tue, Feb 17, 2015 at 3:29 AM, Craig Ringer wrote: >> After spending a while working on the BDR extension I've found that the >> current documentation on the SPI and bgworkers could use some more detail. >> >> In the process I've put cross reference labels in for most chapter headings, >> as I got sick of seeing "Chapter 33" (or whatever) everywhere in the docs. >> I'd like to progressively add them to every section, refentry, chapter, etc >> that has an id. >> >> I hope this is useful. > > Per Peter, 0001 is not wanted. I tend to agree with him on that point > of style. Patch 0002 makes the docs build fail unless 0001 is applied > first, so I can't pursue that unless you want to revise that > accordingly. I've committed 0003, and will look at 0004 next. + + + Use of this field is deprecated. It should be set to + NULL then bgw_library_name + and bgw_function_name should be used instead. + I don't think bgw_main is exactly deprecated. It's fine to use it if the function is in the core code; it just can't be safely used for functions in dynamically loaded shared libraries. Maybe that's close enough to "deprecated" that we should just call it deprecated, but I'm slightly reluctant to use that word. bgw_notify_pid is the PID of a PostgreSQL backend process to which the postmaster should send SIGUSR1 - when the process is started or exits. It should be 0 for workers registered - at postmaster startup time, or when the backend registering the worker does + when the process is started or exits, causing the notified process's latch + to be set. It should be 0 for workers registered + at postmaster startup time, when the backend registering the worker does not wish to wait for the worker to start up. Otherwise, it should be initialized to MyProcPid. This isn't actually right. You can use set_latch_on_sigusr1 to get that behavior, but it's not the default behavior. dboid is InvalidOid, the session is not connected - to any particular database, but shared catalogs can be accessed. + to any particular database, but shared catalogs (tables where + relisshared is true in + pg_class) can be accessed. If username is NULL or useroid is I don't think we should be defining the term "shared catalogs" in the section on background workers. If it needs to be explained, let's do that elsewhere (or find where it's already done) and link to it. A background worker can only call one of these two functions, and only - once. It is not possible to switch databases. + once. It is not possible to switch databases without exiting and restarting + the background worker. That's not really switching databases, though, is it? I've committed some bits of this that seem useful and controversial with rather extensive wordsmithing; let me know if it doesn't look good. -- Robert Haas EnterpriseDB: http://www.enterprisedb.com The Enterprise PostgreSQL Company -- Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org) To make changes to your subscription: http://www.postgresql.org/mailpref/pgsql-docs