Received: from malur.postgresql.org ([217.196.149.56]) by arkaria.postgresql.org with esmtps (TLS1.3) tls TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 (Exim 4.94.2) (envelope-from ) id 1tvIiq-003Fer-Fx for pgsql-general@arkaria.postgresql.org; Thu, 20 Mar 2025 16:26:20 +0000 Received: from localhost ([127.0.0.1] helo=malur.postgresql.org) by malur.postgresql.org with esmtp (Exim 4.94.2) (envelope-from ) id 1tvIio-004LIu-Vb for pgsql-general@arkaria.postgresql.org; Thu, 20 Mar 2025 16:26:18 +0000 Received: from makus.postgresql.org ([2001:4800:3e1:1::229]) by malur.postgresql.org with esmtps (TLS1.3) tls TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 (Exim 4.94.2) (envelope-from ) id 1tvIio-004LI7-CE for pgsql-general@lists.postgresql.org; Thu, 20 Mar 2025 16:26:18 +0000 Received: from mail-oa1-x2f.google.com ([2001:4860:4864:20::2f]) by makus.postgresql.org with esmtps (TLS1.3) tls TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 (Exim 4.96) (envelope-from ) id 1tvIim-000A0G-1W for pgsql-general@postgresql.org; Thu, 20 Mar 2025 16:26:17 +0000 Received: by mail-oa1-x2f.google.com with SMTP id 586e51a60fabf-2c77a5747e0so141488fac.2 for ; Thu, 20 Mar 2025 09:26:16 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1742487975; x=1743092775; darn=postgresql.org; h=cc:to:subject:message-id:date:from:in-reply-to:references :mime-version:from:to:cc:subject:date:message-id:reply-to; bh=96cYO0sn7UibT/KUxn+UBgAx0EXJISfAk+B2uqEIVuA=; b=hKh6H7V3l1Zq24oeZQjvfXJvOeO+plOYOGl8ACxdrWoJ8u8XGs0qnZLSmFcEOeBZed ZXql54L8uKJrxaH4iM9s9elqykcxqGGxF5QKGglQaC5p2UuVmgYAinkbzuZBHlugRX+m Tuq3QjsWjlMFgWSBLLx1Au0X/jkKIJTRoW4URtX2WfkEAy/+CsOAhjv0HEYgSshcOmXx +A1dOPn26Ta+PlBgTOZxdXJ4BkB0UNp2iIm5fCMn5Bo3voOFPiTjkQ4KMrTWdRVXmzzs ZLNB/TqXE1zpPueUkW+J7Dtfke7sk3UB/yZxxeRjkAo6vr7TWmj4LpCoABi4TWcJqSfA E+3A== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1742487975; x=1743092775; h=cc:to:subject:message-id:date:from:in-reply-to:references :mime-version:x-gm-message-state:from:to:cc:subject:date:message-id :reply-to; bh=96cYO0sn7UibT/KUxn+UBgAx0EXJISfAk+B2uqEIVuA=; b=p89gIdsbm+jHaZYrWuXQSZLdZ7YHTBi9eAdcenz2XDES8hVSnv0s6cO6sxocLyb7a9 MmwlwjF7PNQNF1FhGTM2vk4kJ7vDui+1fL2dH5UdBIj327Xk2cmw0Rf+AzQJH8q/Ibd1 pQGr+5y/db6dGJXepmxgjfyWt9GslMU+v/kRU61tRgVq8mmML5F6oRucLPhl9lwqbq7t +ItNv84CMAVqQgQpA6JrDbgKkzLfGsYXj+/M5+DjPDBVpHvRdkMwYarIWpP5weQMo8pf 2fC0kkBQB4h+jFJSKMtlrfg0EUjjkS0E4WpkpZgYBcLmdDOZT4ZrUTMpfIIqNhOUTKh/ i1bA== X-Forwarded-Encrypted: i=1; AJvYcCU2M6cUguWrTOtGJtq/2m9+eBd4fL9VN2bLaBYmpAKG6hbtbw6ja2f+MADLrNbsaFuz5UmPyvH6f9CS0QIY@postgresql.org X-Gm-Message-State: AOJu0YzmXzf6gwzVr65MRsoTrqVtb8fSTmm9QslZxCuVF6vuc3RrlwWy 3VJSFSLt5TwPh9xfqfh6SfOJRpI7vC0IeOsHH+RXojA8iPPYcTyXkR/Oq98+crNSjYYusOhKmF2 y2PwdploAFhu9X5g2euVK5iKYBkA= X-Gm-Gg: ASbGncu4+016nBHPv53bQz8+34GXMV01bgLupf9EhQD1ndCRmOEhRo+tSrJBQd+bpBe n0bXos0eC4CYpXAXUmejUrLtdkLjuZ2v29jk6sQEOLrv7mc5ZAyWWwOSDbMwtXlYUivzlmShlFQ 5Cri1GpQkS0FUrtehIOo9Bh7UI X-Google-Smtp-Source: AGHT+IFqn6RFgQe9vyfrF1bl6JYmH9Ex+2O16MnxcKaHJnXvC+MmQv/r4MzJMrnXrhYtM36mxbA765eVLz5udLOFJRs= X-Received: by 2002:a05:6870:aa98:b0:2c1:5674:940e with SMTP id 586e51a60fabf-2c7802b959cmr110042fac.21.1742487974983; Thu, 20 Mar 2025 09:26:14 -0700 (PDT) MIME-Version: 1.0 References: <3498256.1742065328@sss.pgh.pa.us> <295e06b4-ff5d-4d82-ba56-1bab24be6bbc@aklaver.com> <7a07f957-bb8c-413b-806a-504a5cd12072@aklaver.com> <718368.1742404967@sss.pgh.pa.us> <983724.1742481099@sss.pgh.pa.us> In-Reply-To: From: "David G. Johnston" Date: Thu, 20 Mar 2025 09:25:38 -0700 X-Gm-Features: AQ5f1Jqxz8viXmiALB0aNU14ePWRCeyvtReZGKbCMUzfY2KXdyEZ5EP8qHvfZC4 Message-ID: Subject: Re: After upgrading libpq, the same function(PQftype) call returns a different OID To: Sebastien Flaesch Cc: Tom Lane , Adrian Klaver , M Tarkeshwar Rao , "pgsql-general@postgresql.org" Content-Type: multipart/alternative; boundary="000000000000c641dd0630c898d8" List-Id: List-Help: List-Subscribe: List-Post: List-Owner: List-Archive: Archived-At: Precedence: bulk --000000000000c641dd0630c898d8 Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: quoted-printable On Thu, Mar 20, 2025 at 8:42=E2=80=AFAM Sebastien Flaesch wrote: > > */** > * * Backwards compatibility for ancient random spellings of pg_type OID > macros.* > * * Don't use these names in new code.* > * */* > #define CASHOID MONEYOID > #define LSNOID PG_LSNOID > > #define BOOLOID 16 > #define BYTEAOID 17 > #define CHAROID 18 > #define NAMEOID 19 > #define INT8OID 20 > #define INT2OID 21 > #define INT2VECTOROID 22 > #define INT4OID 23 > #define REGPROCOID 24 > > If I am missing something, then please point me to the correct .h file > that contains #define constants without this scary comment. > > OR.... ( I guess I start to understand the code... ) it this comment only > for: > Yes, that blank line separating LSNOID and BOOLOID blocks the comment from applying to the items after the blank line. That is a fairly common convention, using whitespace to break things up. Also, assigning one macro to another is quite distinct from assigning a constant to a name; making the "backward compatibility" aspect of this comment only meaningfully apply to those two items. > And sorry if I consider constant names like these (without any prefix suc= h > as PG_TYPE_) > We spelled PG_TYPE_ as OID and put it on the end. A boolean as an object is by definition a type. Context clues are important, not every pattern gets spelled out in prose. > #define BOOLOID 16 > #define BYTEAOID 17 > #define CHAROID 18 > #define NAMEOID 19 > #define INT8OID 20 > #define INT2OID 21 > > Arrogance does not help here, clarity and better API doc would. > > To my knowledge the current API doc for this hasn't had any comments of this sort for a very long time. All documentation can be improved because every reader comes at it from a different starting point. Do you have a concrete suggestion for what you think should be changed, and why? My take away from this thread is that a single report isn't usually enough to go searching hard for ways to tweak the documentation for readability; nor has this one pointed out any outright errors to be fixed. In short, we expect that some subset of readers will ask us questions on the mailing list because that is the reality of things. That said, I am curious as to the education flow a developer, not linking in this specific header to their code, would go through in order to learn about type OIDs and make use of them in their project. Maybe that flow is good, maybe not. It's a rare flow and there are many things to do in the project. So my curiosity may not get satiated. As you brought this up and are invested in the outcome you have more motivation than probably anyone else to dive into it and make concrete suggestions for change. All that said, a comment at the top of what is probably the most important section of the header seems warranted. Even if it is just mostly formality. Mentioning the constant-ness of the integers should be part of that. David J. --000000000000c641dd0630c898d8 Content-Type: text/html; charset="UTF-8" Content-Transfer-Encoding: quoted-printable
On Thu, Mar 20, 2025 at 8:42=E2=80=AFAM Sebastien Flaesch = <sebastien.flaesch@4js.com<= /a>> wrote:

/*
=C2=A0* Backwards compatibility for ancient random spellings of pg_type = OID macros.
=C2=A0* Don't use these names in new code.
=C2=A0*/
#define CASHOID MONEYOID
#define LSNOID =C2=A0PG_LSNOID

#define BOOLOID 16
#define BYTEAOID 17
#define CHAROID 18
#define NAMEOID 19
#define INT8OID 20
#define INT2OID 21
#define INT2VECTOROID 22
#define INT4OID 23
#define REGPROCOID 24

If I am missing something, then please point me to the correct .h file that= contains #define constants without this scary comment.

OR.... ( I guess I start to understand the code... ) it this comment only f= or:

Yes, that blank line se= parating LSNOID=C2=A0and BOOLOID blocks the comment from applying to the it= ems after the blank line.=C2=A0 That is a fairly common convention, using w= hitespace to break things up.=C2=A0 Also, assigning=C2=A0one macro to anoth= er is quite distinct from assigning=C2=A0a constant to a name; making the &= quot;backward compatibility" aspect of this comment only meaningfully = apply to those two items.


We spelled PG_= TYPE_=C2=A0 as OID and put it on the end.=C2=A0 A boolean as an object is b= y definition a type.=C2=A0 Context clues are important, not every pattern g= ets spelled out in prose.

<= /div>

To my knowledge the current API doc for= this hasn't had any comments of this sort for a very long time.=C2=A0 = All documentation can be improved because every reader comes at it from a d= ifferent starting point.=C2=A0 Do you have a concrete suggestion for what y= ou think should be changed, and why?=C2=A0 My take away from this thread is= that a single report isn't usually enough to go searching hard for way= s to tweak the documentation for readability; nor has this one pointed out = any outright errors to be fixed.=C2=A0 In short, we expect that some subset= of readers will ask us questions on the mailing list because that is the r= eality of things.

That said, I am curious as to the ed= ucation flow a developer, not linking in this specific header to their code= , would go through in order to learn about type OIDs and make use of them i= n their project.=C2=A0 Maybe that flow is good, maybe not.=C2=A0 It's a= rare flow and there are many things to do in the project.=C2=A0 So my curi= osity=C2=A0may not get satiated.=C2=A0 As you brought this up and are inves= ted in the outcome you have more motivation than probably anyone else to di= ve into it and make concrete suggestions for change.

A= ll that said, a comment at the top of what is probably the most important s= ection of the header seems warranted.=C2=A0 Even if it is just mostly forma= lity.=C2=A0 Mentioning the constant-ness of the integers should be part of = that.

David J.


--000000000000c641dd0630c898d8--