Thread: [PATCH] Document that directly callable functions may use fn_extra
Hi all
For example, SQL functions use fn_extra in init_sql_fcache, plpgsql uses it in plpgsql_compile, but also most of the array functions use it for a type cache.
--
I was a puzzled by src/backend/utils/fmgr/README and fmgr.h's descriptions of fcinfo->flinfo->fn_extra (FmgrInfo.fn_extra) as they seem to conflict with actual usage.
The docs suggest that fl_extra is for the use of function call handlers, but in practice it's also used heavily by function implementations as a cache space.
For example, SQL functions use fn_extra in init_sql_fcache, plpgsql uses it in plpgsql_compile, but also most of the array functions use it for a type cache.
I'm inclined to change the docs to say that functions called directly by the fmgr may also use fn_extra (per existing practice). Handlers that wrap functions usually called directly by the fmgr must save and restore fn_extra or leave it untouched.
Trivial patch to do the above attached.
Attachment
On 5/28/15 10:15 PM, Craig Ringer wrote: > I was a puzzled by src/backend/utils/fmgr/README and fmgr.h's > descriptions of fcinfo->flinfo->fn_extra (FmgrInfo.fn_extra) as they > seem to conflict with actual usage. > > The docs suggest that fl_extra is for the use of function call handlers, > but in practice it's also used heavily by function implementations as a > cache space. The documentation could also be updated about this. It mentions using fn_extra for PL handlers, gist functions, and set-returning functions, but it doesn't say that you can use it any old function for anything you want. I'm not sure how up to date that README actually is. It looks more like a historical document describing the original proposal.
On 5/29/15 10:21 AM, Peter Eisentraut wrote: > On 5/28/15 10:15 PM, Craig Ringer wrote: >> I was a puzzled by src/backend/utils/fmgr/README and fmgr.h's >> descriptions of fcinfo->flinfo->fn_extra (FmgrInfo.fn_extra) as they >> seem to conflict with actual usage. >> >> The docs suggest that fl_extra is for the use of function call handlers, >> but in practice it's also used heavily by function implementations as a >> cache space. > > The documentation could also be updated about this. It mentions using > fn_extra for PL handlers, gist functions, and set-returning functions, > but it doesn't say that you can use it any old function for anything you > want. > > I'm not sure how up to date that README actually is. It looks more like > a historical document describing the original proposal. FWIW, I think it'd be good to also document what lifetime you can expect out of something in fn_extra. I realize you can figure it out from fn_mcxt, but I don't know that that's terribly obvious to others. -- Jim Nasby, Data Architect, Blue Treble Consulting, Austin TX Data in Trouble? Get it in Treble! http://BlueTreble.com