Subject: Adding a new access method (long)

From: "Schenkelaars.V.F" <[email-masked]>
Date: Mon, 27 Jul 92 16:13:58 MET DST

Dear Postgres Group,

I'm preparing to create a new access method for postgres. I`ve 
studied the R-tree code as provided with the postgres system and 
have come to teh following "recipe":

The Reactive Tree is a modified R-tree so I can use the
rtree functions as a template.
I have to create the following functions for my access method the
Reactive Tree:
Reactgettuple      (rtgettuple)
Reactinsert        (rtinsert)
Reactdelete        (rtdelete)
Reactbeginscan     (rtbegins)
Reactrescan        (rtrescan)
Reactendscan       (rtendscan)
Reactmarkpos       (rtmarkpos)
Reactrestrpos      (rtrestrpos)
Reactbuild         (rtbuild)

These functions are registred in the pg_proc relation.

My first question: Are these the only one I have to make or
am I missing some functions?

Next I append a tuple to pg_am.  
pg_am
 (
 amname = char16 ,		<=  "Reactive-tree"
 amowner = oid ,		<=  is added automaticly
 amkind = char ,		<=  "o" ? but what does this mean?
 amstrategies = int2 ,		<=  Do I have to give the number of
				    strategies here? btree has 5 but
				    rtree does have 5 here too. I
				    assumed the rtree has got 8 
                                    strategies, or am I wrong?
 amsupport = int2 ,		<=  number of support functions: Union,
                                    Intersect and Size ?
 amgettuple = regproc ,		<=  Reactgettuple
 aminsert = regproc ,		<=  Reactdelete
 amdelete = regproc ,		<=  Reactdelete
 amgetattr = regproc ,		<=  - ? unknown to me
 amsetlock = regproc ,		<=  - ? unknown to me
 amsettid = regproc ,		<=  - ? unknown to me
 amfreetuple = regproc ,	<=  - ? unknown to me
 ambeginscan = regproc ,	<=  Reactbeginscan
 amrescan = regproc ,		<=  Reactrescan
 amendscan = regproc ,		<=  Reactendscan
 ammarkpos = regproc ,		<=  Reactmarkpos
 amrestrpos = regproc ,		<=  Reactrestrpos
 amopen = regproc ,		<=  - ? unknown to me
 amclose = regproc ,		<=  - ? unknown to me
 ambuild = regproc ,		<=  Reactbuild 
 amcreate = regproc ,		<=  - ? unknown to me
 amdestroy = regproc		<=  - ? unknown to me
 )

Could yould answer the questionmarks in this table. I guess it just
doesn`t aplly to the rtree access method.

Next I have to create a opclass. But since the Reactive tree is 
similar to thre R-tree I just can use the R-tree opclasses. Or
am I wrong?

After this I should be able to define a Reactive Tree index:

define index react-tree on test using Reactive-tree (bbox box_ops)`

where test is a relation with attribute bbox of type box.

My final question is: Is this the correct "recipe" for 
adding an access method. Or did I miss something. 

I don't want to waste a lot of time trying things that won't
work. So I`ll be very pleased if you could answer my questions.

Regards
     ____________________
 \  / . _   _  _   _  |
  \/ ( ( \ (_ (-' ( \ |

--------------------------------------------------------------------------------
Vincent F. Schenkelaars				|
Company: FEL-TNO                                | Private:
Email  : [email-masked]	|
address: Oude Waalsdorperweg 63			| Groenhovenstraat 12
         Postbus 96864				|
         2509 JG  Den Haag			| 2311 BT  Leiden
         The Netherlands			| The Netherlands
Phone  : Holland 070-3264221			| Holland 071-125576
Fax    : Holland 070-3280961			|
--------------------------------------------------------------------------------
We apologize for the inconvenience.

---

From: <[email-masked]>
Date: Tue, 28 Jul 92 15:54:50 PDT

>	am I missing some functions?

no, these are all the routines you're required to define.  however,
if you look at the rtree code, you'll see that there are some
helper routines called (in particular) by beginscan and endscan.
these routines are

	rtregscan()	-- register the fact that you've just begun
			   a new scan on an rtree
	rtdropscan()	-- all done with this scan; forget about it
	rtadjscans()	-- after physical deletion of a tuple from
			   an rtree page, adjust any scans that were
			   affected.

the point of these routines is to support the vacuum cleaner.  when
we vacuum an index relation, we physically delete any index entries
that point at dead heap tuples.  since this may change the layout of
a page that some scans are pointing at, we call rtadjscans() after
physical deletion of an index entry.  this routine is responsible for
'moving' the current tuple pointer of all scans so that they point
at some sensible location.

>	 amowner = oid ,		<=  is added automaticly

actually, amowner isn't filled in automatically, but it isn't used
for anything, either.

>	 amkind = char ,		<=  "o" ? but what does this mean?

you can disregard amkind; it's left over from the pleistocene and
serves no useful purpose.

>	                                    strategies, or am I wrong?

you're right; this is a bug.  this should be eight for rtrees.  i've
made the change here.

>	 amsupport = int2 ,		<=  number of support functions: Union,

correct; for rtrees, this is 3.

>	 amfreetuple = regproc ,	<=  - ? unknown to me

these routines are intended to support high-concurrency indexed
access methods, but aren't used by any of the extant access methods.

>	 amclose = regproc ,		<=  - ? unknown to me

if you have special allocation routines you need to call at relation
open time (unlikely to be the case), you can define these.  otherwise,
the system will call index_open, which allocates a relation descriptor
and fills in some administrative information in the system caches.

>	 amdestroy = regproc		<=  - ? unknown to me

the same statements apply to amcreate and amdestroy as amopen and
amclose.  if it's the case that you need to do special processing
when you create or destroy a reactive tree, then you can define
these.  otherwise, we have a system routine that allocates a file
and initializes the system catalogs correctly.

>	similar to thre R-tree I just can use the R-tree opclasses. Or

correct.

>	adding an access method. Or did I miss something. 

this is correct.

i'd be interested in merging your work on reactive trees into the
distributed version of postgres if you get them working.

					mike