Restructuring plancache.c API

I've been thinking about supporting automatic replan of cached plans
using specific parameter values, as has been discussed several times,
at greatest length in this thread:
http://archives.postgresql.org/pgsql-hackers/2010-02/msg00607.php
There doesn't seem to be full consensus about what the control method
ought to be, but right at the moment I'm thinking about mechanism not
policy. I think that what we need to do is restructure the API of
plancache.c to make it more amenable to returning "throwaway" plans.
It can already do that to some extent using the fully_planned = false
code path, but that's not the design center and it was shoehorned in
in perhaps a less than clean fashion. I want to rearrange it so there's
an explicit notion of three levels of cacheable object:

1. Raw parse tree + source string. These obviously never change.

2. The result tree of parsing and rewriting (ie, the output of
pg_analyze_and_rewrite applied to level 1). This can change, but
only as a result of schema changes on the tables and other objects
referenced in the query. We already have entirely adequate mechanisms
for recognizing when this has to be rebuilt.

3. The finished plan (ie, the output of pg_plan_queries applied to level
2). This might be either cached for reuse, or a throwaway object,
depending on the control mechanism's decisions.

I think we could get rid of the fully_planned switch and instead design
the API around caching levels 1 and 2. Then there's a GetCachedPlan
function (replacing RevalidateCachedPlan) that returns a finished plan,
but it's unspecified whether you get a persistent cached plan or a
throwaway one. The control mechanism would execute inside this
function. We'd still have ReleaseCachedPlan, which would take care of
throwing away the plan if it's throwaway.

Right now the API is structured so that the initial creator of a
cacheable plan has to build levels 2 and 3 first, and the plancache.c
code just copies that data into persistent storage. I'm thinking that
might have been a mistake. Maybe we should just have the caller hand
over the data for level 1, with parse analysis + rewrite done solely
internally within plancache.c. The level-2 data wouldn't be exposed
outside plancache.c at all.

With this focus, the name "plancache" becomes a little bit of a
misnomer, but I am inclined to stick with it because a better name
isn't apparent. "rewritecache" isn't an improvement really.

Comments?

regards, tom lane