diff options
Diffstat (limited to 'doc/src/FAQ/FAQ_DEV.html')
| -rw-r--r-- | doc/src/FAQ/FAQ_DEV.html | 764 |
1 files changed, 387 insertions, 377 deletions
diff --git a/doc/src/FAQ/FAQ_DEV.html b/doc/src/FAQ/FAQ_DEV.html index 07f63e3a86a..2d00bdc5cad 100644 --- a/doc/src/FAQ/FAQ_DEV.html +++ b/doc/src/FAQ/FAQ_DEV.html @@ -27,39 +27,169 @@ <CENTER> - <H2>Questions</H2> + <H2>General Questions</H2> </CENTER> - <A href="#1">1</A>) What tools are available for developers?<BR> - <A href="#2">2</A>) What books are good for developers?<BR> - <A href="#3">3</A>) Why do we use <I>palloc</I>() and - <I>pfree</I>() to allocate memory?<BR> - <A href="#4">4</A>) Why do we use <I>Node</I> and <I>List</I> to - make data structures?<BR> - <A href="#5">5</A>) How do I add a feature or fix a bug?<BR> - <A href="#6">6</A>) How do I download/update the current source + <A href="#1.1">1.1</A>) How do I get involved in PostgreSQL + development?<BR> + <A href="#1.2">1.2</A>) How do I add a feature or fix a bug?<BR> + <A href="#1.3">1.3</A>) How do I download/update the current source tree?<BR> - <A href="#7">7</A>) How do I test my changes?<BR> - <A href="#7">7</A>) I just added a field to a structure. What else - should I do?<BR> - <A href="#8">8</A>) Why are table, column, type, function, view + <A href="#1.4">1.4</A>) How do I test my changes?<BR> + <A href="#1.5">1.5</A>) What tools are available for developers?<BR> + <A href="#1.6">1.6</A>) What books are good for developers?<BR> + <A href="#1.7">1.7</A>) What is configure all about?<BR> + <A href="#1.8">1.8</A>) How do I add a new port?<BR> + <A href="#1.9">1.9</A>) Why don't we use threads in the backend?<BR> + <A href="#1.10">1.10</A>) How are RPM's packaged?<BR> + <A href="#1.11">1.11</A>) How are CVS branches handled?<BR> + + <H2>Technical Questions</H2> + <A href="#2.1">2.1</A>) How do I efficiently access information in + tables from the backend code?<BR> + <A href="#2.2">2.2</A>) Why are table, column, type, function, view names sometimes referenced as <I>Name</I> or <I>NameData,</I> and sometimes as <I>char *?</I><BR> - <A href="#9">9</A>) How do I efficiently access information in - tables from the backend code?<BR> - <A href="#10">10</A>) What is elog()?<BR> - <A href="#11">11</A>) What is configure all about?<BR> - <A href="#12">12</A>) How do I add a new port?<BR> - <A href="#13">13</A>) What is CommandCounterIncrement()?<BR> - <A href="#14">14</A>) Why don't we use threads in the backend?<BR> - <A href="#15">15</A>) How are RPM's packaged?<BR> - <A href="#16">16</A>) How are CVS branches handled?<BR> - <A href="#17">17</A>) How do I get involved in PostgreSQL - development?<BR> + <A href="#2.3">2.3</A>) Why do we use <I>Node</I> and <I>List</I> to + make data structures?<BR> + <A href="#2.4">2.4</A>) I just added a field to a structure. What else + should I do?<BR> + <A href="#2.5">2.5</A>) Why do we use <I>palloc</I>() and + <I>pfree</I>() to allocate memory?<BR> + <A href="#2.6">2.6</A>) What is elog()?<BR> + <A href="#2.7">2.7</A>) What is CommandCounterIncrement()?<BR> <BR> <HR> - <H3><A name="1">1</A>) What tools are available for + <CENTER> + <H2>General Questions</H2> + </CENTER> + + <H3><A name="1.1">1.1</A>) How go I get involved in PostgreSQL + development?</H3> + + <P>This was written by Lamar Owen:</P> + + <P>2001-06-22</P> + + <B>What open source development process is used by the PostgreSQL + team?</B> + + <P>Read HACKERS for six months (or a full release cycle, whichever + is longer). Really. HACKERS _is_the process. The process is not + well documented (AFAIK -- it may be somewhere that I am not aware + of) -- and it changes continually.</P> + + <B>What development environment (OS, system, compilers, etc) is + required to develop code?</B> + + <P><A href="developers.postgresql.org">Developers Corner</A> on the + website has links to this information. The distribution tarball + itself includes all the extra tools and documents that go beyond a + good Unix-like development environment. In general, a modern unix + with a modern gcc, GNU make or equivalent, autoconf (of a + particular version), and good working knowledge of those tools are + required.</P> + + <B>What areas need support?</B> + + <P>The TODO list.</P> + + <P>You've made the first step, by finding and subscribing to + HACKERS. Once you find an area to look at in the TODO, and have + read the documentation on the internals, etc, then you check out a + current CVS,write what you are going to write (keeping your CVS + checkout up to date in the process), and make up a patch (as a + context diff only) and send to the PATCHES list, prefereably.</P> + + <P>Discussion on the patch typically happens here. If the patch + adds a major feature, it would be a good idea to talk about it + first on the HACKERS list, in order to increase the chances of it + being accepted, as well as toavoid duplication of effort. Note that + experienced developers with a proven track record usually get the + big jobs -- for more than one reason. Also note that PostgreSQL is + highly portable -- nonportable code will likely be dismissed out of + hand.</P> + + <P>Once your contributions get accepted, things move from there. + Typically, you would be added as a developer on the list on the + website when one of the other developers recommends it. Membership + on the steering committee is by invitation only, by the other + steering committee members, from what I have gathered watching + froma distance.</P> + + <P>I make these statements from having watched the process for over + two years.</P> + + <P>To see a good example of how one goes about this, search the + archives for the name 'Tom Lane' and see what his first post + consisted of, and where he took things. In particular, note that + this hasn't been _that_ long ago -- and his bugfixing and general + deep knowledge with this codebase is legendary. Take a few days to + read after him. And pay special attention to both the sheer + quantity as well as the painstaking quality of his work. Both are + in high demand.</P> + + <H3><A name="1.2">1.2</A>) How do I add a feature or fix a bug?</H3> + + <P>The source code is over 250,000 lines. Many problems/features + are isolated to one specific area of the code. Others require + knowledge of much of the source. If you are confused about where to + start, ask the hackers list, and they will be glad to assess the + complexity and give pointers on where to start.</P> + + <P>Another thing to keep in mind is that many fixes and features + can be added with surprisingly little code. I often start by adding + code, then looking at other areas in the code where similar things + are done, and by the time I am finished, the patch is quite small + and compact.</P> + + <P>When adding code, keep in mind that it should use the existing + facilities in the source, for performance reasons and for + simplicity. Often a review of existing code doing similar things is + helpful.</P> + + <H3><A name="1.3">1.3</A>) How do I download/update the current source + tree?</H3> + + <P>There are several ways to obtain the source tree. Occasional + developers can just get the most recent source tree snapshot from + ftp.postgresql.org. For regular developers, you can use CVS. CVS + allows you to download the source tree, then occasionally update + your copy of the source tree with any new changes. Using CVS, you + don't have to download the entire source each time, only the + changed files. Anonymous CVS does not allows developers to update + the remote source tree, though privileged developers can do this. + There is a CVS FAQ on our web site that describes how to use remote + CVS. You can also use CVSup, which has similarly functionality, and + is available from ftp.postgresql.org.</P> + + <P>To update the source tree, there are two ways. You can generate + a patch against your current source tree, perhaps using the + make_diff tools mentioned above, and send them to the patches list. + They will be reviewed, and applied in a timely manner. If the patch + is major, and we are in beta testing, the developers may wait for + the final release before applying your patches.</P> + + <P>For hard-core developers, Marc(scrappy@postgresql.org) will give + you a Unix shell account on postgresql.org, so you can use CVS to + update the main source tree, or you can ftp your files into your + account, patch, and cvs install the changes directly into the + source tree.</P> + + <H3><A name="1.4">1.4</A>) How do I test my changes?</H3> + + <P>First, use <I>psql</I> to make sure it is working as you expect. + Then run <I>src/test/regress</I> and get the output of + <I>src/test/regress/checkresults</I> with and without your changes, + to see that your patch does not change the regression test in + unexpected ways. This practice has saved me many times. The + regression tests test the code in ways I would never do, and has + caught many bugs in my patches. By finding the problems now, you + save yourself a lot of debugging later when things are broken, and + you can't figure out when it happened.</P> + + <H3><A name="1.5">1.5</A>) What tools are available for developers?</H3> <P>Aside from the User documentation mentioned in the regular FAQ, @@ -179,7 +309,7 @@ There is also a script called <I>unused_oids</I> in <I>pgsql/src/include/catalog</I> that shows the unused oids.</P> - <H3><A name="2">2</A>) What books are good for developers?</H3> + <H3><A name="1.6">1.6</A>) What books are good for developers?</H3> <P>I have four good books, <I>An Introduction to Database Systems,</I> by C.J. Date, Addison, Wesley, <I>A Guide to the SQL @@ -192,288 +322,7 @@ on-line written by Jim Gray at <A href= "http://www.benchmarkresources.com">http://www.benchmarkresources.com.</A></P> - <H3><A name="3">3</A>) Why do we use <I>palloc</I>() and - <I>pfree</I>() to allocate memory?</H3> - - <P><I>palloc()</I> and <I>pfree()</I> are used in place of malloc() - and free() because we automatically free all memory allocated when - a transaction completes. This makes it easier to make sure we free - memory that gets allocated in one place, but only freed much later. - There are several contexts that memory can be allocated in, and - this controls when the allocated memory is automatically freed by - the backend.</P> - - <H3><A name="4">4</A>) Why do we use <I>Node</I> and <I>List</I> to - make data structures?</H3> - - <P>We do this because this allows a consistent way to pass data - inside the backend in a flexible way. Every node has a - <I>NodeTag</I> which specifies what type of data is inside the - Node. <I>Lists</I> are groups of <I>Nodes chained together as a - forward-linked list.</I></P> - - <P>Here are some of the <I>List</I> manipulation commands:</P> - - <BLOCKQUOTE> - <DL> - <DT>lfirst(i)</DT> - - <DD>return the data at list element <I>i.</I></DD> - - <DT>lnext(i)</DT> - - <DD>return the next list element after <I>i.</I></DD> - - <DT>foreach(i, list)</DT> - - <DD> - loop through <I>list,</I> assigning each list element to - <I>i.</I> It is important to note that <I>i</I> is a List *, - not the data in the <I>List</I> element. You need to use - <I>lfirst(i)</I> to get at the data. Here is a typical code - snipped that loops through a List containing <I>Var *'s</I> - and processes each one: -<PRE> -<CODE>List *i, *list; - - foreach(i, list) - { - Var *var = lfirst(i); - - /* process var here */ - } -</CODE> -</PRE> - </DD> - - <DT>lcons(node, list)</DT> - - <DD>add <I>node</I> to the front of <I>list,</I> or create a - new list with <I>node</I> if <I>list</I> is <I>NIL.</I></DD> - - <DT>lappend(list, node)</DT> - - <DD>add <I>node</I> to the end of <I>list.</I> This is more - expensive that lcons.</DD> - - <DT>nconc(list1, list2)</DT> - - <DD>Concat <I>list2</I> on to the end of <I>list1.</I></DD> - - <DT>length(list)</DT> - - <DD>return the length of the <I>list.</I></DD> - - <DT>nth(i, list)</DT> - - <DD>return the <I>i</I>'th element in <I>list.</I></DD> - - <DT>lconsi, ...</DT> - - <DD>There are integer versions of these: <I>lconsi, lappendi, - nthi.</I> <I>List's</I> containing integers instead of Node - pointers are used to hold list of relation object id's and - other integer quantities.</DD> - </DL> - </BLOCKQUOTE> - You can print nodes easily inside <I>gdb.</I> First, to disable - output truncation when you use the gdb <I>print</I> command: -<PRE> -<CODE>(gdb) set print elements 0 -</CODE> -</PRE> - Instead of printing values in gdb format, you can use the next two - commands to print out List, Node, and structure contents in a - verbose format that is easier to understand. List's are unrolled - into nodes, and nodes are printed in detail. The first prints in a - short format, and the second in a long format: -<PRE> -<CODE>(gdb) call print(any_pointer) - (gdb) call pprint(any_pointer) -</CODE> -</PRE> - The output appears in the postmaster log file, or on your screen if - you are running a backend directly without a postmaster. - - <H3><A name="5">5</A>) How do I add a feature or fix a bug?</H3> - - <P>The source code is over 250,000 lines. Many problems/features - are isolated to one specific area of the code. Others require - knowledge of much of the source. If you are confused about where to - start, ask the hackers list, and they will be glad to assess the - complexity and give pointers on where to start.</P> - - <P>Another thing to keep in mind is that many fixes and features - can be added with surprisingly little code. I often start by adding - code, then looking at other areas in the code where similar things - are done, and by the time I am finished, the patch is quite small - and compact.</P> - - <P>When adding code, keep in mind that it should use the existing - facilities in the source, for performance reasons and for - simplicity. Often a review of existing code doing similar things is - helpful.</P> - - <H3><A name="6">6</A>) How do I download/update the current source - tree?</H3> - - <P>There are several ways to obtain the source tree. Occasional - developers can just get the most recent source tree snapshot from - ftp.postgresql.org. For regular developers, you can use CVS. CVS - allows you to download the source tree, then occasionally update - your copy of the source tree with any new changes. Using CVS, you - don't have to download the entire source each time, only the - changed files. Anonymous CVS does not allows developers to update - the remote source tree, though privileged developers can do this. - There is a CVS FAQ on our web site that describes how to use remote - CVS. You can also use CVSup, which has similarly functionality, and - is available from ftp.postgresql.org.</P> - - <P>To update the source tree, there are two ways. You can generate - a patch against your current source tree, perhaps using the - make_diff tools mentioned above, and send them to the patches list. - They will be reviewed, and applied in a timely manner. If the patch - is major, and we are in beta testing, the developers may wait for - the final release before applying your patches.</P> - - <P>For hard-core developers, Marc(scrappy@postgresql.org) will give - you a Unix shell account on postgresql.org, so you can use CVS to - update the main source tree, or you can ftp your files into your - account, patch, and cvs install the changes directly into the - source tree.</P> - - <H3><A name="6">6</A>) How do I test my changes?</H3> - - <P>First, use <I>psql</I> to make sure it is working as you expect. - Then run <I>src/test/regress</I> and get the output of - <I>src/test/regress/checkresults</I> with and without your changes, - to see that your patch does not change the regression test in - unexpected ways. This practice has saved me many times. The - regression tests test the code in ways I would never do, and has - caught many bugs in my patches. By finding the problems now, you - save yourself a lot of debugging later when things are broken, and - you can't figure out when it happened.</P> - - <H3><A name="7">7</A>) I just added a field to a structure. What - else should I do?</H3> - - <P>The structures passing around from the parser, rewrite, - optimizer, and executor require quite a bit of support. Most - structures have support routines in <I>src/backend/nodes</I> used - to create, copy, read, and output those structures. Make sure you - add support for your new field to these files. Find any other - places the structure may need code for your new field. <I>mkid</I> - is helpful with this (see above).</P> - - <H3><A name="8">8</A>) Why are table, column, type, function, view - names sometimes referenced as <I>Name</I> or <I>NameData,</I> and - sometimes as <I>char *?</I></H3> - - <P>Table, column, type, function, and view names are stored in - system tables in columns of type <I>Name.</I> Name is a - fixed-length, null-terminated type of <I>NAMEDATALEN</I> bytes. - (The default value for NAMEDATALEN is 32 bytes.)</P> -<PRE> -<CODE>typedef struct nameData - { - char data[NAMEDATALEN]; - } NameData; - typedef NameData *Name; -</CODE> -</PRE> - Table, column, type, function, and view names that come into the - backend via user queries are stored as variable-length, - null-terminated character strings. - - <P>Many functions are called with both types of names, ie. - <I>heap_open().</I> Because the Name type is null-terminated, it is - safe to pass it to a function expecting a char *. Because there are - many cases where on-disk names(Name) are compared to user-supplied - names(char *), there are many cases where Name and char * are used - interchangeably.</P> - - <H3><A name="9">9</A>) How do I efficiently access information in - tables from the backend code?</H3> - - <P>You first need to find the tuples(rows) you are interested in. - There are two ways. First, <I>SearchSysCache()</I> and related - functions allow you to query the system catalogs. This is the - preferred way to access system tables, because the first call to - the cache loads the needed rows, and future requests can return the - results without accessing the base table. The caches use system - table indexes to look up tuples. A list of available caches is - located in <I>src/backend/utils/cache/syscache.c.</I> - <I>src/backend/utils/cache/lsyscache.c</I> contains many - column-specific cache lookup functions.</P> - - <P>The rows returned are cache-owned versions of the heap rows. - Therefore, you must not modify or delete the tuple returned by - <I>SearchSysCache()</I>. What you <I>should</I> do is release it - with <I>ReleaseSysCache()</I> when you are done using it; this - informs the cache that it can discard that tuple if necessary. If - you neglect to call <I>ReleaseSysCache()</I>, then the cache entry - will remain locked in the cache until end of transaction, which is - tolerable but not very desirable.</P> - - <P>If you can't use the system cache, you will need to retrieve the - data directly from the heap table, using the buffer cache that is - shared by all backends. The backend automatically takes care of - loading the rows into the buffer cache.</P> - - <P>Open the table with <I>heap_open().</I> You can then start a - table scan with <I>heap_beginscan(),</I> then use - <I>heap_getnext()</I> and continue as long as - <I>HeapTupleIsValid()</I> returns true. Then do a - <I>heap_endscan().</I> <I>Keys</I> can be assigned to the - <I>scan.</I> No indexes are used, so all rows are going to be - compared to the keys, and only the valid rows returned.</P> - - <P>You can also use <I>heap_fetch()</I> to fetch rows by block - number/offset. While scans automatically lock/unlock rows from the - buffer cache, with <I>heap_fetch(),</I> you must pass a - <I>Buffer</I> pointer, and <I>ReleaseBuffer()</I> it when - completed.</P> - - <P>Once you have the row, you can get data that is common to all - tuples, like <I>t_self</I> and <I>t_oid,</I> by merely accessing - the <I>HeapTuple</I> structure entries. If you need a - table-specific column, you should take the HeapTuple pointer, and - use the <I>GETSTRUCT()</I> macro to access the table-specific start - of the tuple. You then cast the pointer as a <I>Form_pg_proc</I> - pointer if you are accessing the pg_proc table, or - <I>Form_pg_type</I> if you are accessing pg_type. You can then - access the columns by using a structure pointer:</P> -<PRE> -<CODE>((Form_pg_class) GETSTRUCT(tuple))->relnatts -</CODE> -</PRE> - You must not directly change <I>live</I> tuples in this way. The - best way is to use <I>heap_modifytuple()</I> and pass it your - original tuple, and the values you want changed. It returns a - palloc'ed tuple, which you pass to <I>heap_replace().</I> You can - delete tuples by passing the tuple's <I>t_self</I> to - <I>heap_destroy().</I> You use <I>t_self</I> for - <I>heap_update()</I> too. Remember, tuples can be either system - cache copies, which may go away after you call - <I>ReleaseSysCache()</I>, or read directly from disk buffers, which - go away when you <I>heap_getnext()</I>, <I>heap_endscan</I>, or - <I>ReleaseBuffer()</I>, in the <I>heap_fetch()</I> case. Or it may - be a palloc'ed tuple, that you must <I>pfree()</I> when finished. - - <H3><A name="10">10</A>) What is elog()?</H3> - - <P><I>elog()</I> is used to send messages to the front-end, and - optionally terminate the current query being processed. The first - parameter is an elog level of <I>NOTICE,</I> <I>DEBUG,</I> - <I>ERROR,</I> or <I>FATAL.</I> <I>NOTICE</I> prints on the user's - terminal and the postmaster logs. <I>DEBUG</I> prints only in the - postmaster logs. <I>ERROR</I> prints in both places, and terminates - the current query, never returning from the call. <I>FATAL</I> - terminates the backend process. The remaining parameters of - <I>elog</I> are a <I>printf</I>-style set of parameters to - print.</P> - - <H3><A name="11">11</A>) What is configure all about?</H3> + <H3><A name="1.7">1.7</A>) What is configure all about?</H3> <P>The files <I>configure</I> and <I>configure.in</I> are part of the GNU <I>autoconf</I> package. Configure allows us to test for @@ -497,7 +346,7 @@ all files derived by configure are removed, so you see only the file contained in the source distribution.</P> - <H3><A name="12">12</A>) How do I add a new port?</H3> + <H3><A name="1.8">1.8</A>) How do I add a new port?</H3> <P>There are a variety of places that need to be modified to add a new port. First, start in the <I>src/template</I> directory. Add an @@ -516,20 +365,7 @@ handling. There is a <I>backend/port</I> directory if you need special files for your OS.</P> - <H3><A name="13">13</A>) What is CommandCounterIncrement()?</H3> - - <P>Normally, transactions can not see the rows they modify. This - allows <CODE>UPDATE foo SET x = x + 1</CODE> to work correctly.</P> - - <P>However, there are cases where a transactions needs to see rows - affected in previous parts of the transaction. This is accomplished - using a Command Counter. Incrementing the counter allows - transactions to be broken into pieces so each piece can see rows - modified by previous pieces. <I>CommandCounterIncrement()</I> - increments the Command Counter, creating a new part of the - transaction.</P> - - <H3><A name="14">14</A>) Why don't we use threads in the + <H3><A name="1.9">1.9</A>) Why don't we use threads in the backend?</H3> <P>There are several reasons threads are not used:</P> @@ -545,7 +381,7 @@ <LI>The backend code would be more complex.</LI> </UL> - <H3><A name="15">15</A>) How are RPM's packaged?</H3> + <H3><A name="1.10">1.10</A>) How are RPM's packaged?</H3> <P>This was written by Lamar Owen:</P> @@ -650,7 +486,7 @@ <P>Of course, there are many projects that DO include all the files necessary to build RPMs from their Official Tarball (TM).</P> - <H3><A name="16">16</A>) How are CVS branches managed?</H3> + <H3><A name="1.11">1.11</A>) How are CVS branches managed?</H3> <P>This was written by Tom Lane:</P> @@ -720,70 +556,244 @@ dot-release or two, so that we won't have to double-patch the first wave of fixes.</P> - <H3><A name="17">17</A>) How go I get involved in PostgreSQL - development?</H3> + <CENTER> + <H2>Technical Questions</H2> + </CENTER> - <P>This was written by Lamar Owen:</P> + <H3><A name="2.1">2.1</A>) How do I efficiently access information in + tables from the backend code?</H3> - <P>2001-06-22</P> + <P>You first need to find the tuples(rows) you are interested in. + There are two ways. First, <I>SearchSysCache()</I> and related + functions allow you to query the system catalogs. This is the + preferred way to access system tables, because the first call to + the cache loads the needed rows, and future requests can return the + results without accessing the base table. The caches use system + table indexes to look up tuples. A list of available caches is + located in <I>src/backend/utils/cache/syscache.c.</I> + <I>src/backend/utils/cache/lsyscache.c</I> contains many + column-specific cache lookup functions.</P> - <B>What open source development process is used by the PostgreSQL - team?</B> + <P>The rows returned are cache-owned versions of the heap rows. + Therefore, you must not modify or delete the tuple returned by + <I>SearchSysCache()</I>. What you <I>should</I> do is release it + with <I>ReleaseSysCache()</I> when you are done using it; this + informs the cache that it can discard that tuple if necessary. If + you neglect to call <I>ReleaseSysCache()</I>, then the cache entry + will remain locked in the cache until end of transaction, which is + tolerable but not very desirable.</P> - <P>Read HACKERS for six months (or a full release cycle, whichever - is longer). Really. HACKERS _is_the process. The process is not - well documented (AFAIK -- it may be somewhere that I am not aware - of) -- and it changes continually.</P> + <P>If you can't use the system cache, you will need to retrieve the + data directly from the heap table, using the buffer cache that is + shared by all backends. The backend automatically takes care of + loading the rows into the buffer cache.</P> - <B>What development environment (OS, system, compilers, etc) is - required to develop code?</B> + <P>Open the table with <I>heap_open().</I> You can then start a + table scan with <I>heap_beginscan(),</I> then use + <I>heap_getnext()</I> and continue as long as + <I>HeapTupleIsValid()</I> returns true. Then do a + <I>heap_endscan().</I> <I>Keys</I> can be assigned to the + <I>scan.</I> No indexes are used, so all rows are going to be + compared to the keys, and only the valid rows returned.</P> - <P><A href="developers.postgresql.org">Developers Corner</A> on the - website has links to this information. The distribution tarball - itself includes all the extra tools and documents that go beyond a - good Unix-like development environment. In general, a modern unix - with a modern gcc, GNU make or equivalent, autoconf (of a - particular version), and good working knowledge of those tools are - required.</P> + <P>You can also use <I>heap_fetch()</I> to fetch rows by block + number/offset. While scans automatically lock/unlock rows from the + buffer cache, with <I>heap_fetch(),</I> you must pass a + <I>Buffer</I> pointer, and <I>ReleaseBuffer()</I> it when + completed.</P> - <B>What areas need support?</B> + <P>Once you have the row, you can get data that is common to all + tuples, like <I>t_self</I> and <I>t_oid,</I> by merely accessing + the <I>HeapTuple</I> structure entries. If you need a + table-specific column, you should take the HeapTuple pointer, and + use the <I>GETSTRUCT()</I> macro to access the table-specific start + of the tuple. You then cast the pointer as a <I>Form_pg_proc</I> + pointer if you are accessing the pg_proc table, or + <I>Form_pg_type</I> if you are accessing pg_type. You can then + access the columns by using a structure pointer:</P> +<PRE> +<CODE>((Form_pg_class) GETSTRUCT(tuple))->relnatts +</CODE> +</PRE> + You must not directly change <I>live</I> tuples in this way. The + best way is to use <I>heap_modifytuple()</I> and pass it your + original tuple, and the values you want changed. It returns a + palloc'ed tuple, which you pass to <I>heap_replace().</I> You can + delete tuples by passing the tuple's <I>t_self</I> to + <I>heap_destroy().</I> You use <I>t_self</I> for + <I>heap_update()</I> too. Remember, tuples can be either system + cache copies, which may go away after you call + <I>ReleaseSysCache()</I>, or read directly from disk buffers, which + go away when you <I>heap_getnext()</I>, <I>heap_endscan</I>, or + <I>ReleaseBuffer()</I>, in the <I>heap_fetch()</I> case. Or it may + be a palloc'ed tuple, that you must <I>pfree()</I> when finished. - <P>The TODO list.</P> + <H3><A name="2.2">2.2</A>) Why are table, column, type, function, view + names sometimes referenced as <I>Name</I> or <I>NameData,</I> and + sometimes as <I>char *?</I></H3> - <P>You've made the first step, by finding and subscribing to - HACKERS. Once you find an area to look at in the TODO, and have - read the documentation on the internals, etc, then you check out a - current CVS,write what you are going to write (keeping your CVS - checkout up to date in the process), and make up a patch (as a - context diff only) and send to the PATCHES list, prefereably.</P> + <P>Table, column, type, function, and view names are stored in + system tables in columns of type <I>Name.</I> Name is a + fixed-length, null-terminated type of <I>NAMEDATALEN</I> bytes. + (The default value for NAMEDATALEN is 32 bytes.)</P> +<PRE> +<CODE>typedef struct nameData + { + char data[NAMEDATALEN]; + } NameData; + typedef NameData *Name; +</CODE> +</PRE> + Table, column, type, function, and view names that come into the + backend via user queries are stored as variable-length, + null-terminated character strings. - <P>Discussion on the patch typically happens here. If the patch - adds a major feature, it would be a good idea to talk about it - first on the HACKERS list, in order to increase the chances of it - being accepted, as well as toavoid duplication of effort. Note that - experienced developers with a proven track record usually get the - big jobs -- for more than one reason. Also note that PostgreSQL is - highly portable -- nonportable code will likely be dismissed out of - hand.</P> + <P>Many functions are called with both types of names, ie. + <I>heap_open().</I> Because the Name type is null-terminated, it is + safe to pass it to a function expecting a char *. Because there are + many cases where on-disk names(Name) are compared to user-supplied + names(char *), there are many cases where Name and char * are used + interchangeably.</P> - <P>Once your contributions get accepted, things move from there. - Typically, you would be added as a developer on the list on the - website when one of the other developers recommends it. Membership - on the steering committee is by invitation only, by the other - steering committee members, from what I have gathered watching - froma distance.</P> + <H3><A name="2.3">2.3</A>) Why do we use <I>Node</I> and <I>List</I> to + make data structures?</H3> - <P>I make these statements from having watched the process for over - two years.</P> + <P>We do this because this allows a consistent way to pass data + inside the backend in a flexible way. Every node has a + <I>NodeTag</I> which specifies what type of data is inside the + Node. <I>Lists</I> are groups of <I>Nodes chained together as a + forward-linked list.</I></P> + + <P>Here are some of the <I>List</I> manipulation commands:</P> + + <BLOCKQUOTE> + <DL> + <DT>lfirst(i)</DT> + + <DD>return the data at list element <I>i.</I></DD> + + <DT>lnext(i)</DT> + + <DD>return the next list element after <I>i.</I></DD> + + <DT>foreach(i, list)</DT> + + <DD> + loop through <I>list,</I> assigning each list element to + <I>i.</I> It is important to note that <I>i</I> is a List *, + not the data in the <I>List</I> element. You need to use + <I>lfirst(i)</I> to get at the data. Here is a typical code + snipped that loops through a List containing <I>Var *'s</I> + and processes each one: +<PRE> +<CODE>List *i, *list; + + foreach(i, list) + { + Var *var = lfirst(i); + + /* process var here */ + } +</CODE> +</PRE> + </DD> + + <DT>lcons(node, list)</DT> + + <DD>add <I>node</I> to the front of <I>list,</I> or create a + new list with <I>node</I> if <I>list</I> is <I>NIL.</I></DD> + + <DT>lappend(list, node)</DT> + + <DD>add <I>node</I> to the end of <I>list.</I> This is more + expensive that lcons.</DD> + + <DT>nconc(list1, list2)</DT> + + <DD>Concat <I>list2</I> on to the end of <I>list1.</I></DD> + + <DT>length(list)</DT> + + <DD>return the length of the <I>list.</I></DD> + + <DT>nth(i, list)</DT> + + <DD>return the <I>i</I>'th element in <I>list.</I></DD> + + <DT>lconsi, ...</DT> + + <DD>There are integer versions of these: <I>lconsi, lappendi, + nthi.</I> <I>List's</I> containing integers instead of Node + pointers are used to hold list of relation object id's and + other integer quantities.</DD> + </DL> + </BLOCKQUOTE> + You can print nodes easily inside <I>gdb.</I> First, to disable + output truncation when you use the gdb <I>print</I> command: +<PRE> +<CODE>(gdb) set print elements 0 +</CODE> +</PRE> + Instead of printing values in gdb format, you can use the next two + commands to print out List, Node, and structure contents in a + verbose format that is easier to understand. List's are unrolled + into nodes, and nodes are printed in detail. The first prints in a + short format, and the second in a long format: +<PRE> +<CODE>(gdb) call print(any_pointer) + (gdb) call pprint(any_pointer) +</CODE> +</PRE> + The output appears in the postmaster log file, or on your screen if + you are running a backend directly without a postmaster. + + <H3><A name="2.4">2.4</A>) I just added a field to a structure. What + else should I do?</H3> + + <P>The structures passing around from the parser, rewrite, + optimizer, and executor require quite a bit of support. Most + structures have support routines in <I>src/backend/nodes</I> used + to create, copy, read, and output those structures. Make sure you + add support for your new field to these files. Find any other + places the structure may need code for your new field. <I>mkid</I> + is helpful with this (see above).</P> + + <H3><A name="2.5">2.5</A>) Why do we use <I>palloc</I>() and + <I>pfree</I>() to allocate memory?</H3> + + <P><I>palloc()</I> and <I>pfree()</I> are used in place of malloc() + and free() because we automatically free all memory allocated when + a transaction completes. This makes it easier to make sure we free + memory that gets allocated in one place, but only freed much later. + There are several contexts that memory can be allocated in, and + this controls when the allocated memory is automatically freed by + the backend.</P> + + <H3><A name="2.6">2.6</A>) What is elog()?</H3> + + <P><I>elog()</I> is used to send messages to the front-end, and + optionally terminate the current query being processed. The first + parameter is an elog level of <I>NOTICE,</I> <I>DEBUG,</I> + <I>ERROR,</I> or <I>FATAL.</I> <I>NOTICE</I> prints on the user's + terminal and the postmaster logs. <I>DEBUG</I> prints only in the + postmaster logs. <I>ERROR</I> prints in both places, and terminates + the current query, never returning from the call. <I>FATAL</I> + terminates the backend process. The remaining parameters of + <I>elog</I> are a <I>printf</I>-style set of parameters to + print.</P> + + <H3><A name="2.7">2.7</A>) What is CommandCounterIncrement()?</H3> + + <P>Normally, transactions can not see the rows they modify. This + allows <CODE>UPDATE foo SET x = x + 1</CODE> to work correctly.</P> + + <P>However, there are cases where a transactions needs to see rows + affected in previous parts of the transaction. This is accomplished + using a Command Counter. Incrementing the counter allows + transactions to be broken into pieces so each piece can see rows + modified by previous pieces. <I>CommandCounterIncrement()</I> + increments the Command Counter, creating a new part of the + transaction.</P> - <P>To see a good example of how one goes about this, search the - archives for the name 'Tom Lane' and see what his first post - consisted of, and where he took things. In particular, note that - this hasn't been _that_ long ago -- and his bugfixing and general - deep knowledge with this codebase is legendary. Take a few days to - read after him. And pay special attention to both the sheer - quantity as well as the painstaking quality of his work. Both are - in high demand.</P> </BODY> </HTML> - |