# Changeset 52262

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

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

File:
1 edited

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

 r32083 --> \section segmentintro Segment Library

Authors: CERL \author CERL \section segmentintro Introduction

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. the caller.

Note: All routines and global variables in this library, documented or undocumented, start with the prefix segment_. 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. 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 that must be included in any code using these routines: [footnote] \verbatim \c grass/segment.h that must be included in any code using these routines: \code #include \endverbatim \endcode \see \ref Loading_the_Segment_Library.

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

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 fd for use as a segment file. The corresponding nonsegmented data matrix, which is to be transferred to the segment file, is nrows by ncols. The segment file is to be formed of segments which are srows by scols. The data items have length len bytes. For example, if the data type is int, len is sizeof(int) . formed of segments which are srows by scols. The data items have length len bytes. For example, if the data type is int, len is sizeof(int).

The next step is to initialize a SEGMENT structure to be associated with a segment file formatted by segment_format. segment file formatted by segment_format().

int segment_init (SEGMENT *seg, int fd, int nsegs) initialize segment structureInitializes the seg structure. The file on fd is a segment file created by segment_format and must be open for structure

Initializes the seg structure. The file on fd is a segment file created by segment_format() and must be open for reading and writing. The segment file configuration parameters nrows, ncols, srows, scols, and len, as written to the file by will be retained in memory. The minimum value allowed is 1.

Note. The size of a segment is scols*srows*len plus a few \note The size of a segment is scols*srows*len plus a few bytes for managing each segment.

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

Transfers nonsegmented matrix data, row by row, into a segment file.  Seg is the segment structure that was configured from a call to segment_init. Buf should contain ncols*len to segment_init(). Buf should contain ncols*len bytes of data to be transferred to the segment file. Row specifies the row from the data matrix being transferred.

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

Provides random read access to the segmented data. It gets len bytes of data into value from the segment file seg for the corresponding row and col in the

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

Provides random write access to the segmented data. It copies len bytes of data from value into the segment structure seg for the corresponding row and col in Return codes are: 1 if ok; else -1 could not seek or write segment file.

After random reading and writing is finished, the pending updates must be

int segment_flush (SEGMENT *seg) flush pending updates to diskForces all pending updates generated by segment_put() to be written to the int segment_flush (SEGMENT *seg), flush pending updates to disk

Forces all pending updates generated by segment_put() to be written to the segment file seg. Must be called after the final segment_put() to force all pending updates to disk. Must also be called before the first call to segment_get_row. to segment_get_row().

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

Transfers data from a segment file, row by row, into memory (which can then be written to a regular matrix file) . Seg is the segment structure that was configured from a call to segment_init. segment structure that was configured from a call to segment_init(). Buf will be filled with ncols*len bytes of data corresponding to the row in the data matrix.

int segment_release (SEGMENT *seg) free allocated memoryReleases the int segment_release (SEGMENT *seg) free allocated memory

Releases the allocated memory associated with the segment file seg. Does not close the file. Does not flush the data which may be pending from previous created, formatted and then closed: \verbatim \code fd = creat (file, 0666); close(fd); \endverbatim \

\verbatim \code #include fd = open (file, O_RDWR); segment_init (&seg, fd, nseg) segment_init (&seg, fd, nseg); for (row = 0; row < nrows; row++) { segment_put_row (&seg, buf, row); // code to get original matrix data for row into buf segment_put_row (&seg, buf, row); } \endverbatim \endcode values, the step which transfers data from the original matrix to the segment file, using segment_put_row() , could be omitted, since segment_format will fill the segment file with zeros.

The data can now be accessed directly using segment_get. For example, segment_format() will fill the segment file with zeros.

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_get (&seg, &value, row, col); \endverbatim

Similarly segment_put() can be used to change data values in the \endcode

Similarly segment_put() can be used to change data values in the segment file: \verbatim \code int value; segment_put (&seg, &value, row, col); \endverbatim

WARNING: It is an easy mistake to pass a value directly to \endcode \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

\verbatim \code segment_flush (&seg); segment_get_row (&seg, buf, row); // code to put buf into a matrix data file for row } \endverbatim \endcode

\verbatim \code segment_release (&seg); close (fd); \endverbatim

Note: The Segment Library does not know the name of the \endcode \note The Segment Library 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.

The library is loaded by specifying $(SEGMENTLIB) in the Makefile. The library is loaded by specifying \code$(SEGMENTLIB) \endcode in the Makefile.

Note: See TracChangeset for help on using the changeset viewer.