[GRASS-SVN] r52262 - grass/branches/releasebranch_6_4/lib/segment
svn_grass at osgeo.org
svn_grass at osgeo.org
Sun Jul 1 04:58:09 PDT 2012
Author: neteler
Date: 2012-07-01 04:58:09 -0700 (Sun, 01 Jul 2012)
New Revision: 52262
Modified:
grass/branches/releasebranch_6_4/lib/segment/segmentlib.dox
Log:
more doxygen-style syntax to produce standardized output (partial backport of r52237)
Modified: grass/branches/releasebranch_6_4/lib/segment/segmentlib.dox
===================================================================
--- grass/branches/releasebranch_6_4/lib/segment/segmentlib.dox 2012-07-01 11:41:15 UTC (rev 52261)
+++ grass/branches/releasebranch_6_4/lib/segment/segmentlib.dox 2012-07-01 11:58:09 UTC (rev 52262)
@@ -3,13 +3,11 @@
by M. Neteler 8/2005
-->
-\section segmentintro Segment Library
+\author CERL
+\section segmentintro Introduction
<P>
-Authors: CERL
-
-<P>
Large data files which contain data in a matrix format often need to be
accessed in a nonsequential or random manner. This requirement complicates
the programming.
@@ -37,7 +35,7 @@
code and requires no significant amount of memory to hold the data. But the
i/o involved will certainly degrade performance. Method (3) is a mixture of
(1) and (2) . Memory requirements are fixed and data is read from the data
-file only when not already in memory. Howev er the programming is more
+file only when not already in memory. However the programming is more
complex.
<P>
@@ -61,9 +59,8 @@
data is paged into memory as needed and the requested data is returned to
the caller.
-<P>
-<B>Note:</B> All routines and global variables in this library, documented
-or undocumented, start with the prefix <B>segment_.</B> To avoid name
+\note All routines and global variables in this library, documented
+or undocumented, start with the prefix \c segment_. To avoid name
conflicts, programmers should not create variables or routines in their own
modules which use this prefix.
@@ -74,13 +71,15 @@
The routines in the <I>Segment Library</I> are described below, more or
less in the order they would logically be used in a module. They use a data
structure called SEGMENT which is defined in the header file
-<grass/segment.h> that must be included in any code using these
-routines: [footnote]
+\c grass/segment.h that must be included in any code using these
+routines:
-\verbatim
+\code
#include <grass/segment.h>
-\endverbatim
+\endcode
+\see \ref Loading_the_Segment_Library.
+
<P>
The first step is to create a file which is properly formatted for use by
the <I>Segment Library</I> routines:
@@ -88,7 +87,9 @@
<P>
int segment_format (int fd, int nrows, int ncols, int srows, int scols,
- int len) format a segment fileThe segmentation routines require a disk file
+ int len), format a segment file
+<P>
+ The segmentation routines require a disk file
to be used for paging segments in and out of memory. This routine formats the
file open for write on file descriptor <B>fd</B> for use as a segment file.
A segment file must be formatted before it can be processed by other segment
@@ -99,9 +100,9 @@
<P>
The corresponding nonsegmented data matrix, which is to be transferred to the
segment file, is <B>nrows</B> by <B>ncols.</B> The segment file is to be
- formed of segments which are <B>srows</B> by <B>scols.</B> The data items
- have length <B>len</B> bytes. For example, if the <I>data type is int</I>,
- <B><I>len</I> </B><I>is sizeof(int) .</I>
+ formed of segments which are <B>srows</B> by <B>scols</B>. The data items
+ have length <B>len</B> bytes. For example, if the data type is <I>int</I>,
+ <B><I>len</I></B> is <I>sizeof(int)</I>.
<P>
Return codes are: 1 ok; else -1 could not seek or write <I>fd</I>, or -3
@@ -109,20 +110,21 @@
<P>
The next step is to initialize a SEGMENT structure to be associated with a
-segment file formatted by <I>segment_format.</I>
+segment file formatted by segment_format().
<P>
int segment_init (SEGMENT *seg, int fd, int nsegs) initialize segment
- structureInitializes the <B>seg</B> structure. The file on <B>fd</B> is
- a segment file created by <I>segment_format</I> and must be open for
+ structure
+<P>
+ Initializes the <B>seg</B> structure. The file on <B>fd</B> is
+ a segment file created by segment_format() and must be open for
reading and writing. The segment file configuration parameters <I>nrows,
ncols, srows, scols</I>, and <I>len</I>, as written to the file by
<I>segment_format</I>, are read from the file and stored in the
<B>seg</B> structure. <B>Nsegs</B> specifies the number of segments that
will be retained in memory. The minimum value allowed is 1.
-<P>
-<B>Note.</B> The size of a segment is <I>scols*srows*len</I> plus a few
+\note The size of a segment is <I>scols*srows*len</I> plus a few
bytes for managing each segment.
<P>
@@ -133,9 +135,11 @@
<P>
int segment_put_row (SEGMENT *seg, char *buf, int row) write row to
- segment fileTransfers nonsegmented matrix data, row by row, into a segment
+ segment file
+<P>
+ Transfers nonsegmented matrix data, row by row, into a segment
file. <B>Seg</B> is the segment structure that was configured from a call
- to <I>segment_init.</I> <B>Buf</B> should contain <I>ncols*len</I>
+ to segment_init(). <B>Buf</B> should contain <I>ncols*len</I>
bytes of data to be transferred to the segment file. <B>Row</B> specifies
the row from the data matrix being transferred.
@@ -147,7 +151,9 @@
<P>
int segment_get (SEGMENT *seg, char *value, int row, int col) get value
- from segment fileProvides random read access to the segmented data. It gets
+ from segment file
+<P>
+ Provides random read access to the segmented data. It gets
<I>len</I> bytes of data into <B>value</B> from the segment file
<B>seg</B> for the corresponding <B>row</B> and <B>col</B> in the
original data matrix.
@@ -157,7 +163,9 @@
<P>
int segment_put (SEGMENT *seg, char *value, int row, int col) put
- value to segment fileProvides random write access to the segmented data. It
+ value to segment file
+<P>
+ Provides random write access to the segmented data. It
copies <I>len</I> bytes of data from <B>value</B> into the segment
structure <B>seg</B> for the corresponding <B>row</B> and <B>col</B> in
the original data matrix.
@@ -169,18 +177,18 @@
<P>
Return codes are: 1 if ok; else -1 could not seek or write segment file.
-
-
<P>
After random reading and writing is finished, the pending updates must be
flushed to disk:
<P>
-int segment_flush (SEGMENT *seg) flush pending updates to diskForces
- all pending updates generated by <I>segment_put()</I> to be written to the
+int segment_flush (SEGMENT *seg), flush pending updates to disk
+<P>
+ Forces
+ all pending updates generated by segment_put() to be written to the
segment file <B>seg.</B> Must be called after the final segment_put() to
force all pending updates to disk. Must also be called before the first call
- to <I>segment_get_row.</I>
+ to segment_get_row().
<P>
Now the data in segment file can be read row by row and transferred to a normal
@@ -188,9 +196,11 @@
<P>
int segment_get_row (SEGMENT *seg, char *buf, int row) read row from
- segment fileTransfers data from a segment file, row by row, into memory
+ segment file
+<P>
+ Transfers data from a segment file, row by row, into memory
(which can then be written to a regular matrix file) . <B>Seg</B> is the
- segment structure that was configured from a call to <I>segment_init.</I>
+ segment structure that was configured from a call to segment_init().
<B>Buf</B> will be filled with <I>ncols*len</I> bytes of data
corresponding to the <B>row</B> in the data matrix.
@@ -201,7 +211,9 @@
Finally, memory allocated in the SEGMENT structure is freed:
<P>
-int segment_release (SEGMENT *seg) free allocated memoryReleases the
+int segment_release (SEGMENT *seg) free allocated memory
+<P>
+ Releases the
allocated memory associated with the segment file <B>seg.</B> Does not close
the file. Does not flush the data which may be pending from previous
<I>segment_put()</I> calls.
@@ -216,15 +228,16 @@
The first step is the creation and formatting of a segment file. A file is
created, formatted and then closed:
-
-\verbatim
+\code
fd = creat (file, 0666);
segment_format (fd, nrows, ncols, srows, scols, sizeof(int));
close(fd);
-\endverbatim
+\
+
+
<P>
The next step is the conversion of the nonsegmented matrix data into segment
file format. The segment file is reopened for read and write, initialized, and
@@ -232,7 +245,7 @@
file:
-\verbatim
+\code
#include <fcntl.h>
int buf[NCOLS];
@@ -240,40 +253,41 @@
SEGMENT seg;
fd = open (file, O_RDWR);
-segment_init (&seg, fd, nseg)
+segment_init (&seg, fd, nseg);
for (row = 0; row < nrows; row++)
{
- <code to get original matrix data for row into buf>
- segment_put_row (&seg, buf, row);
+ // code to get original matrix data for row into buf
+
+ segment_put_row (&seg, buf, row);
}
-\endverbatim
+\endcode
<P>
Of course if the intention is only to add new values rather than update existing
values, the step which transfers data from the original matrix to the segment
file, using segment_put_row() , could be omitted, since
-<I>segment_format</I> will fill the segment file with zeros.
+segment_format() will fill the segment file with zeros.
<P>
-The data can now be accessed directly using <I>segment_get.</I> For example,
+The data can now be accessed directly using segment_get(). For example,
to get the value at a given row and column:
-\verbatim
+\code
int value;
SEGMENT seg;
segment_get (&seg, &value, row, col);
-\endverbatim
+\endcode
<P>
-Similarly <I>segment_put()</I> can be used to change data values in the
+Similarly segment_put() can be used to change data values in the
segment file:
-\verbatim
+\code
int value;
SEGMENT seg;
@@ -281,16 +295,16 @@
value = 10;
segment_put (&seg, &value, row, col);
-\endverbatim
+\endcode
-<P>
-<B>WARNING:</B> It is an easy mistake to pass a value directly to
+
+\warning It is an easy mistake to pass a value directly to
segment_put(). The following should be avoided:
-\verbatim
-segment_put (&seg, 10, row, col); /* this will not work */
-\endverbatim
+\code
+segment_put (&seg, 10, row, col); // this will not work
+\endcode
<P>
Once the random access processing is complete, the data would be extracted
@@ -298,31 +312,30 @@
follows:
-\verbatim
+\code
segment_flush (&seg);
for (row = 0; row < nrows; row++)
{
segment_get_row (&seg, buf, row);
- <code to put buf into a matrix data file for row>
-
+ // code to put buf into a matrix data file for row
}
-\endverbatim
+\endcode
<P>
Finally, the memory allocated for use by the segment routines would be
released and the file closed:
-\verbatim
+\code
segment_release (&seg);
close (fd);
-\endverbatim
+\endcode
-<P>
-<B>Note:</B> The <I>Segment Library</I> does not know the name of the
+
+\note The <I>Segment Library</I> does not know the name of the
segment file. It does not attempt to remove the file. If the file is only
temporary, the programmer should remove the file after closing it.
@@ -331,7 +344,11 @@
\section Loading_the_Segment_Library Loading the Segment Library
<P>
-The library is loaded by specifying $(SEGMENTLIB) in the Makefile.
+The library is loaded by specifying
+\code
+$(SEGMENTLIB)
+\endcode
+in the Makefile.
<P>
See \ref Compiling_and_Installing_GRASS_Modules for a complete
More information about the grass-commit
mailing list