Changeset 52262


Ignore:
Timestamp:
Jul 1, 2012 4:58:09 AM (4 years ago)
Author:
neteler
Message:

more doxygen-style syntax to produce standardized output (partial backport of r52237)

File:
1 edited

Legend:

Unmodified
Added
Removed
  • grass/branches/releasebranch_6_4/lib/segment/segmentlib.dox

    r32083 r52262  
    44  -->
    55
    6 \section segmentintro Segment Library
    7 
    8 
    9 <P>
    10 Authors: CERL
     6\author CERL
     7
     8\section segmentintro Introduction
    119
    1210<P>
     
    3836i/o involved will certainly degrade performance. Method (3) is a mixture of
    3937(1) and (2) . Memory requirements are fixed and data is read from the data
    40 file only when not already in memory. Howev er the programming is more
     38file only when not already in memory. However the programming is more
    4139complex.
    4240
     
    6260the caller.
    6361
    64 <P>
    65 <B>Note:</B> All routines and global variables in this library, documented
    66 or undocumented, start with the prefix <B>segment_.</B> To avoid name
     62\note All routines and global variables in this library, documented
     63or undocumented, start with the prefix \c segment_. To avoid name
    6764conflicts, programmers should not create variables or routines in their own
    6865modules which use this prefix.
     
    7572less in the order they would logically be used in a module. They use a data
    7673structure called SEGMENT which is defined in the header file
    77 <grass/segment.h> that must be included in any code using these
    78 routines: [footnote]
    79 
    80 \verbatim
     74\c grass/segment.h that must be included in any code using these
     75routines:
     76
     77\code
    8178#include <grass/segment.h>
    82 \endverbatim
     79\endcode
     80
     81\see \ref Loading_the_Segment_Library.
    8382
    8483<P>
     
    8988<P>
    9089int segment_format (int fd, int nrows, int ncols, int srows, int scols,
    91   int len) format a segment fileThe segmentation routines require a disk file
     90  int len), format a segment file
     91<P>
     92  The segmentation routines require a disk file
    9293  to be used for paging segments in and out of memory. This routine formats the
    9394  file open for write on file descriptor <B>fd</B> for use as a segment file.
     
    100101The corresponding nonsegmented data matrix, which is to be transferred to the
    101102  segment file, is <B>nrows</B> by <B>ncols.</B> The segment file is to be
    102   formed of segments which are <B>srows</B> by <B>scols.</B> The data items
    103   have length <B>len</B> bytes. For example, if the <I>data type is int</I>,
    104   <B><I>len</I> </B><I>is sizeof(int) .</I>
     103  formed of segments which are <B>srows</B> by <B>scols</B>. The data items
     104  have length <B>len</B> bytes. For example, if the data type is <I>int</I>,
     105  <B><I>len</I></B> is <I>sizeof(int)</I>.
    105106
    106107<P>
     
    110111<P>
    111112The next step is to initialize a SEGMENT structure to be associated with a
    112 segment file formatted by <I>segment_format.</I>
     113segment file formatted by segment_format().
    113114
    114115<P>
    115116int segment_init (SEGMENT *seg, int fd, int nsegs) initialize segment
    116   structureInitializes the <B>seg</B> structure. The file on <B>fd</B> is
    117   a segment file created by <I>segment_format</I> and must be open for
     117  structure
     118<P>
     119  Initializes the <B>seg</B> structure. The file on <B>fd</B> is
     120  a segment file created by segment_format() and must be open for
    118121  reading and writing. The segment file configuration parameters <I>nrows,
    119122    ncols, srows, scols</I>, and <I>len</I>, as written to the file by
     
    122125  will be retained in memory. The minimum value allowed is 1.
    123126
    124 <P>
    125 <B>Note.</B> The size of a segment is <I>scols*srows*len</I> plus a few
     127\note The size of a segment is <I>scols*srows*len</I> plus a few
    126128  bytes for managing each segment.
    127129
     
    134136<P>
    135137int segment_put_row (SEGMENT *seg, char *buf, int row) write row to
    136   segment fileTransfers nonsegmented matrix data, row by row, into a segment
     138  segment file
     139<P>
     140  Transfers nonsegmented matrix data, row by row, into a segment
    137141  file.  <B>Seg</B> is the segment structure that was configured from a call
    138   to <I>segment_init.</I> <B>Buf</B> should contain <I>ncols*len</I>
     142  to segment_init(). <B>Buf</B> should contain <I>ncols*len</I>
    139143  bytes of data to be transferred to the segment file. <B>Row</B> specifies
    140144  the row from the data matrix being transferred.
     
    148152<P>
    149153int segment_get (SEGMENT *seg, char *value, int row, int col) get value
    150   from segment fileProvides random read access to the segmented data. It gets
     154  from segment file
     155<P>
     156  Provides random read access to the segmented data. It gets
    151157  <I>len</I> bytes of data into <B>value</B> from the segment file
    152158  <B>seg</B> for the corresponding <B>row</B> and <B>col</B> in the
     
    158164<P>
    159165int segment_put (SEGMENT *seg, char *value, int row, int col) put
    160   value to segment fileProvides random write access to the segmented data. It
     166  value to segment file
     167<P>
     168  Provides random write access to the segmented data. It
    161169  copies <I>len</I> bytes of data from <B>value</B> into the segment
    162170  structure <B>seg</B> for the corresponding <B>row</B> and <B>col</B> in
     
    170178Return codes are: 1 if ok; else -1 could not seek or write segment file.
    171179
    172 
    173 
    174180<P>
    175181After random reading and writing is finished, the pending updates must be
     
    177183
    178184<P>
    179 int segment_flush (SEGMENT *seg) flush pending updates to diskForces
    180   all pending updates generated by <I>segment_put()</I> to be written to the
     185int segment_flush (SEGMENT *seg), flush pending updates to disk
     186<P>
     187  Forces
     188  all pending updates generated by segment_put() to be written to the
    181189  segment file <B>seg.</B> Must be called after the final segment_put() to
    182190  force all pending updates to disk. Must also be called before the first call
    183   to <I>segment_get_row.</I>
     191  to segment_get_row().
    184192
    185193<P>
     
    189197<P>
    190198int segment_get_row (SEGMENT *seg, char *buf, int row) read row from
    191   segment fileTransfers data from a segment file, row by row, into memory
     199  segment file
     200<P>
     201  Transfers data from a segment file, row by row, into memory
    192202  (which can then be written to a regular matrix file) . <B>Seg</B> is the
    193   segment structure that was configured from a call to <I>segment_init.</I>
     203  segment structure that was configured from a call to segment_init().
    194204  <B>Buf</B> will be filled with <I>ncols*len</I> bytes of data
    195205  corresponding to the <B>row</B> in the data matrix.
     
    202212
    203213<P>
    204 int segment_release (SEGMENT *seg) free allocated memoryReleases the
     214int segment_release (SEGMENT *seg) free allocated memory
     215<P>
     216  Releases the
    205217  allocated memory associated with the segment file <B>seg.</B> Does not close
    206218  the file. Does not flush the data which may be pending from previous
     
    217229created, formatted and then closed:
    218230
    219 
    220 \verbatim
     231\code
    221232fd = creat (file, 0666);
    222233
     
    224235
    225236close(fd);
    226 \endverbatim
     237\
     238
     239
    227240
    228241<P>
     
    233246
    234247
    235 \verbatim
     248\code
    236249#include <fcntl.h>
    237250
     
    241254
    242255fd = open (file, O_RDWR);
    243 segment_init (&seg, fd, nseg)
     256segment_init (&seg, fd, nseg);
    244257
    245258for (row = 0; row < nrows; row++)
    246259{
    247  <code to get original matrix data for row into buf>
    248  segment_put_row (&seg, buf, row);
     260    // code to get original matrix data for row into buf
     261
     262    segment_put_row (&seg, buf, row);
    249263}
    250 \endverbatim
     264\endcode
    251265
    252266
     
    255269values, the step which transfers data from the original matrix to the segment
    256270file, using segment_put_row() , could be omitted, since
    257 <I>segment_format</I> will fill the segment file with zeros.
    258 
    259 <P>
    260 The data can now be accessed directly using <I>segment_get.</I> For example,
     271segment_format() will fill the segment file with zeros.
     272
     273<P>
     274The data can now be accessed directly using segment_get(). For example,
    261275to get the value at a given row and column:
    262276
    263 \verbatim
     277\code
    264278int value;
    265279
     
    267281
    268282segment_get (&seg, &value, row, col);
    269 \endverbatim
    270 
    271 <P>
    272 Similarly <I>segment_put()</I> can be used to change data values in the
     283\endcode
     284
     285<P>
     286Similarly segment_put() can be used to change data values in the
    273287segment file:
    274288
    275289
    276 \verbatim
     290\code
    277291int value;
    278292
     
    282296
    283297segment_put (&seg, &value, row, col);
    284 \endverbatim
    285 
    286 <P>
    287 <B>WARNING:</B> It is an easy mistake to pass a value directly to
     298\endcode
     299
     300
     301\warning It is an easy mistake to pass a value directly to
    288302segment_put(). The following should be avoided:
    289303
    290304
    291 \verbatim
    292 segment_put (&seg, 10, row, col); /* this will not work */
    293 \endverbatim
     305\code
     306segment_put (&seg, 10, row, col); // this will not work
     307\endcode
    294308
    295309<P>
     
    299313
    300314
    301 \verbatim
     315\code
    302316segment_flush (&seg);
    303317
     
    306320    segment_get_row (&seg, buf, row);
    307321
    308     <code to put buf into a matrix data file for row>
    309 
     322    // code to put buf into a matrix data file for row
    310323}
    311 \endverbatim
     324\endcode
    312325
    313326<P>
     
    316329
    317330
    318 \verbatim
     331\code
    319332segment_release (&seg);
    320333
    321334close (fd);
    322 \endverbatim
    323 
    324 <P>
    325 <B>Note:</B> The <I>Segment Library</I> does not know the name of the
     335\endcode
     336
     337
     338\note The <I>Segment Library</I> does not know the name of the
    326339segment file. It does not attempt to remove the file. If the file is only
    327340temporary, the programmer should remove the file after closing it.
     
    332345
    333346<P>
    334 The library is loaded by specifying $(SEGMENTLIB) in the Makefile.
     347The library is loaded by specifying
     348\code
     349$(SEGMENTLIB)
     350\endcode
     351in the Makefile.
    335352
    336353<P>
Note: See TracChangeset for help on using the changeset viewer.