Message-ID: <4F395D1A.8070405@gmail.com>
Date: Mon, 13 Feb 2012 13:57:30 -0500
From: Jay Levitt <jay.levitt@gmail.com>
User-Agent: Postbox 3.0.2 (Macintosh/20111203)
MIME-Version: 1.0
To: Tom Lane <tgl@sss.pgh.pa.us>
CC: "pgsql-docs@postgresql.org" <pgsql-docs@postgresql.org>
Subject: Re: [PATCH] Use idiomatic style for varlena structs
References: <4F392203.2040907@gmail.com> <10780.1329148311@sss.pgh.pa.us>
In-Reply-To: <10780.1329148311@sss.pgh.pa.us>
Content-Type: text/plain; charset=ISO-8859-1; format=flowed
Content-Transfer-Encoding: 7bit

Tom Lane wrote:
> Jay Levitt<jay.levitt@gmail.com>  writes:
>> I'm new to the codebase, but I think this patch reflects real-world usage;
>> the PostgreSQL code itself always calls the length field "vl_len_", and I
>> believe int32 is preferred over int4 (yes?)
>
> The point of calling it vl_len_ is that it should never be referenced by
> that name, so I'm not sure that propagating that name into user
> documentation is a good idea.  I do agree with the part of this patch
> that recommends use of SET_VARSIZE.

Ah, ok.  My confusion came from trying to build a new extension, using cube 
as a baseline; cube (and all the other contrib extensions) use vl_len_, so I 
saw a disconnect between the "int4 length" in the manual and the
"int32 vl_len_" in all the real-world examples I had.

My thought was that "vl_len_" *feels* more like a "this is mysterious and 
I'd better not touch it - I'll use that macro", while "length" feels more 
like something I might just set myself if I didn't know better.  But maybe 
not.  Either way, the int32/int4 thing should be fixed.

> For context, the issues you're concerned about only matter when dealing
> with a toastable datatype (not all varlena types are toastable).  The
> particular bit of docs here doesn't pretend to be explaining how to
> write toast-safe code.  I think it might be better from an expository
> standpoint to cover that separately, rather than try to work it into the
> very first pass over the concepts.

Definitely; if anything, that's why I was favoring vl_len_. This is a magic 
field. Do not touch the magic.

Jay