GRASS GIS 8 Programmer's Manual  8.2.2dev(2023)-3d2c704037
defs/segment.h File Reference
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Functions

int Segment_open (SEGMENT *, char *, off_t, off_t, int, int, int, int)
 Initialize segment structure and open segment file. More...
 
int Segment_close (SEGMENT *)
 Free memory allocated to segment, delete temp file. More...
 
int Segment_flush (SEGMENT *)
 Flush pending updates to disk. More...
 
int Segment_format (int, off_t, off_t, int, int, int)
 Format a segment file. More...
 
int Segment_format_nofill (int, off_t, off_t, int, int, int)
 Format a segment file. More...
 
int Segment_get (SEGMENT *, void *, off_t, off_t)
 Get value from segment file. More...
 
int Segment_get_row (const SEGMENT *, void *, off_t)
 
int Segment_init (SEGMENT *, int, int)
 Initialize segment structure. More...
 
int Segment_put (SEGMENT *, const void *, off_t, off_t)
 
int Segment_put_row (const SEGMENT *, const void *, off_t)
 Write row to segment file. More...
 
int Segment_release (SEGMENT *)
 Free memory allocated to segment. More...
 

Function Documentation

◆ Segment_close()

int Segment_close ( SEGMENT SEG)

Free memory allocated to segment, delete temp file.

Releases the allocated memory associated with the segment file seg and deletes the temporary file.

Parameters
[in,out]SEGsegment
Returns
1 if successful
-1 if SEGMENT is not available (not open)

Definition at line 33 of file segment/close.c.

References SEGMENT::cache, SEGMENT::fd, SEGMENT::fname, G_free(), NULL, SEGMENT::open, and Segment_release().

◆ Segment_flush()

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.

Parameters
[in]SEGsegment
Returns
always returns 0

Definition at line 32 of file flush.c.

References SEGMENT::scb::dirty, SEGMENT::scb::n, SEGMENT::nseg, SEGMENT::scb, and seg_pageout().

◆ Segment_format()

int Segment_format ( int  fd,
off_t  nrows,
off_t  ncols,
int  srows,
int  scols,
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.

A segment file must be formatted before it can be processed by other segment routines. The configuration parameters nrows, ncols, srows, scols, and len are written to the beginning of the segment file which is then filled with zeros.

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).

Parameters
[in]fdfile descriptor
[in]nrowsnumber of non-segmented rows
[in]ncolsnumber of non-segmented columns
[in]srowssegment rows
[in]scolssegment columns
[in]lenlength of data type
Returns
1 of successful
-1 if unable to seek or write fd
-3 if illegal parameters are passed

Definition at line 63 of file segment/format.c.

◆ Segment_format_nofill()

int Segment_format_nofill ( int  fd,
off_t  nrows,
off_t  ncols,
int  srows,
int  scols,
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.

A segment file must be formatted before it can be processed by other segment routines. The configuration parameters nrows, ncols, srows, scols, and len are written to the beginning of the segment file which is then filled with zeros.

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).

Note: This version of the function does not fill in the initialized data structures with zeros.

Parameters
[in]fdfile descriptor
[in]nrowsnumber of non-segmented rows
[in]ncolsnumber of non-segmented columns
[in]srowssegment rows
[in]scolssegment columns
[in]lenlength of data type
Returns
1 of successful
-1 if unable to seek or write fd
-3 if illegal parameters are passed

Definition at line 101 of file segment/format.c.

◆ Segment_get()

int Segment_get ( SEGMENT SEG,
void *  buf,
off_t  row,
off_t  col 
)

Get value from segment file.

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

Parameters
[in]SEGsegment
[in,out]bufvalue return buffer
[in]row
[in]col
Returns
1 of successful
-1 if unable to seek or read segment file

Definition at line 39 of file segment/get.c.

References SEGMENT::address, SEGMENT::scb::buf, SEGMENT::cache, SEGMENT::len, SEGMENT::ncols, SEGMENT::scb, and seg_pagein().

◆ Segment_get_row()

int Segment_get_row ( const SEGMENT ,
void *  ,
off_t   
)

Definition at line 43 of file segment/get_row.c.

◆ Segment_init()

int Segment_init ( SEGMENT SEG,
int  fd,
int  nseg 
)

Initialize segment 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 Segment_format(), are read from the file and stored in the seg structure. nsegs specifies the number of segments that will be retained in memory. The minimum value allowed is 1.

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

Parameters
[in,out]SEGsegment
[in]fdfile descriptor
[in]nsegnumber of segments to remain in memory
Returns
1 if successful
-1 if unable to seek or read segment file
-2 if out of memory

Definition at line 59 of file segment/init.c.

References err(), SEGMENT::fd, G_warning(), SEGMENT::nseg, and SEGMENT::open.

◆ Segment_open()

int Segment_open ( SEGMENT SEG,
char *  fname,
off_t  nrows,
off_t  ncols,
int  srows,
int  scols,
int  len,
int  nseg 
)

Initialize segment structure and open segment file.

Initializes the seg structure and prepares a temporary file. This fn is a wrapper for Segment_format() and Segment_init()

Note: The file with name fname will be created anew.

Parameters
[in,out]SEGsegment
[in]fnamefile name
[in]nrowsnumber of non-segmented rows
[in]ncolsnumber of non-segmented columns
[in]srowssegment rows
[in]scolssegment columns
[in]lenlength of data type
[in]nsegnumber of segments to remain in memory
Returns
1 if successful
-1 if file name is invalid
-2 if file write error
-3 if illegal parameters are passed
-4 if file could not be re-opened
-5 if prepared file could not be read
-6 if out of memory

Definition at line 47 of file segment/open.c.

◆ Segment_put()

int Segment_put ( SEGMENT ,
const void *  ,
off_t  ,
off_t   
)

◆ Segment_put_row()

int Segment_put_row ( const SEGMENT SEG,
const void *  buf,
off_t  row 
)

Write row to segment file.

Transfers non-segmented 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 bytes of data to be transferred to the segment file. row specifies the row from the data matrix being transferred.

Parameters
[in,out]SEGsegment
[in]bufdata to write to segment
[in]row
Returns
1 if successful
-1 if unable to seek or write segment file

Definition at line 44 of file segment/put_row.c.

◆ Segment_release()

int Segment_release ( SEGMENT SEG)

Free memory allocated to segment.

Releases the allocated memory associated with the segment file seg.

Note: Does not close the file. Does not flush the data which may be pending from previous Segment_put() calls.

Parameters
[in,out]SEGsegment
Returns
1 if successful
-1 if SEGMENT is not available (not open)

Definition at line 36 of file segment/release.c.

References SEGMENT::agequeue, SEGMENT::scb::buf, SEGMENT::freeslot, G_free(), SEGMENT::load_idx, SEGMENT::nseg, SEGMENT::open, and SEGMENT::scb.

Referenced by Segment_close().