psi::PSIO Class Reference

#include <psio.hpp>

Public Member Functions
int	state ()
	return 1 if activated
void	filecfg_kwd (const char *kwdgrp, const char *kwd, int unit, const char *kwdval)
const std::string &	filecfg_kwd (const char *kwdgrp, const char *kwd, int unit)
	returns the keyword value. If not defined, returns empty string.
void	open (unsigned int unit, int status)
	open unit. status can be PSIO_OPEN_OLD (if existing file is to be opened) or PSIO_OPEN_NEW if new file should be open
void	close (unsigned int unit, int keep)
	close unit. if keep == 0, will remove the file, else keep it
void	rehash (unsigned int unit)
	sync up the object to the file on disk by closing and opening the file, if necessary
int	open_check (unsigned int unit)
	return 1 if unit is open
void	read (unsigned int unit, char *key, char *buffer, ULI size, psio_address start, psio_address *end)
void	write (unsigned int unit, char *key, char *buffer, ULI size, psio_address start, psio_address *end)
void	read_entry (unsigned int unit, char *key, char *buffer, ULI size)
void	write_entry (unsigned int unit, char *key, char *buffer, ULI size)
void	rw (unsigned int unit, char *buffer, psio_address address, ULI size, int wrt)
void	tocclean (unsigned int unit, char *key)
	Delete all TOC entries after the given key. If a blank key is given, the entire TOC will be wiped.
void	tocprint (unsigned int unit, FILE *output)
	Print the table of contents for the given unit.
psio_tocentry *	tocscan (unsigned int unit, char *key)
	Scans the TOC for a particular keyword and returns either a pointer to the entry or NULL to the caller.
void	tocwrite (unsigned int unit)
	Write the table of contents for file number 'unit'. NB: This function should NOT call psio_error because the latter calls it!
Static Public Attributes
static int	_error_exit_code_ = 1
	Upon catastrophic failure, the library will exit() with this code. The default is 1, but can be overridden.

---

Detailed Description

PSIO is an instance of libpsio library. Multiple instances of PSIO are supported.

Each instance can be configured using filecfg_kwd(). The following example best demonstrates how to configure a PSIO instance Lib: Lib->filecfg_kwd("DEFAULT","NAME",-1,"newwfn") // all modules will set filename prefix to newwfn for all units Lib->filecfg_kwd("DEFAULT","NVOLUME",34,"2") // all modules will stripe unit 34 over 2 volumes Lib->filecfg_kwd("CINTS","VOLUME1",-1,"/scratch1/") // module CINTS will access volume 1 of all units under /scratch etc.

Definition at line 22 of file psio.hpp.

---

Member Function Documentation

void PSIO::filecfg_kwd	(	const char *	kwdgrp,
		const char *	kwd,
		int	unit,
		const char *	kwdval
	)

set keyword kwd describing some aspect of configuration of PSIO file unit to value kwdval. kwdgrp specifies the keyword group (useful values are: "DEFAULT", "PSI", and the name of the current executable). If unit is set to -1, this keyword will set the default for all units (this keyword can be further overridden for some units). To specify a keyword that works for a specific unit, set unit to the appropriate number between 0 to PSIO_MAXUNIT.

PSIO understands the following keywords: "name" (specifies the prefix for the filename, i.e. if name is set to "psi" then unit 35 will be named "psi.35"), "nvolume" (number of files over which to stripe this unit, cannot be greater than PSIO_MAXVOL), "volumeX", where X is a positive integer less than or equal to the value of "nvolume".

Definition at line 32 of file filescfg.cc.

Referenced by psi::psirb::Task::prefix(), psio_get_filename_default(), psio_get_numvols_default(), psi::psirb::Task::scratch(), and psi::psirb::Task::Task().

                                           {
  std::string fkwd = fullkwd(kwdgrp, kwd, unit);
  files_keywords_[fkwd] = kwdval;
}

void PSIO::read	(	unsigned int	unit,
		char *	key,
		char *	buffer,
		ULI	size,
		psio_address	start,
		psio_address *	end
	)

Reads data from within a TOC entry from a PSI file.

Parameters:

	unit	= The PSI unit number used to identify the file to all read and write functions.
	key	= The TOC keyword identifying the desired entry.
	buffer	= The buffer to store the data as it is read.
	size	= The number of bytes to read.
	start	= The entry-relative starting page/offset of the desired data.
	end	= A pointer to the entry-relative page/offset for the next byte after the end of the read request.

Definition at line 14 of file read.cc.

References psio_error(), psio_get_address(), psio_get_global_address(), rw(), and tocscan().

Referenced by psio_read(), and rw().

                                                       {
  psio_ud *this_unit;
  psio_tocentry *this_entry;
  psio_address start_toc, start_data, end_data; /* global addresses */
  ULI tocentry_size;
  
  this_unit = &(psio_unit[unit]);
  
  /* Find the entry in the TOC */
  this_entry = tocscan(unit, key);
  
  tocentry_size = sizeof(psio_tocentry) - 2*sizeof(psio_tocentry *);
  
  if (this_entry == NULL) {
    fprintf(stderr, "PSIO_ERROR: Can't find TOC Entry %s\n", key);
    psio_error(unit, PSIO_ERROR_NOTOCENT);
  } else {
    
    /* Compute the global starting page and offset for the data */
    start_toc = this_entry->sadd;
    start_data = psio_get_address(start_toc, tocentry_size);
    start_data = psio_get_global_address(start_data, start);
    
    /* Make sure the block starts and ends within the entry */
    if (start_data.page > this_entry->eadd.page)
      psio_error(unit, PSIO_ERROR_BLKSTART);
    else if ((start_data.page == this_entry->eadd.page) &&(start_data.offset
        > this_entry->eadd.offset))
      psio_error(unit, PSIO_ERROR_BLKSTART);
    
    end_data = psio_get_address(start_data, size);
    if ((end_data.page > this_entry->eadd.page))
      psio_error(unit, PSIO_ERROR_BLKEND);
    else if ((end_data.page == this_entry->eadd.page) &&(end_data.offset
        > this_entry->eadd.offset))
      psio_error(unit, PSIO_ERROR_BLKEND);
    
    /* Update end (an entry-relative address) for the caller */
    *end = psio_get_address(start, size);
  }
  
  /* Now read the actual data from the unit */
  rw(unit, buffer, start_data, size, 0);
  
#ifdef PSIO_STATS
  psio_readlen[unit] += size;
#endif  
}

void PSIO::write	(	unsigned int	unit,
		char *	key,
		char *	buffer,
		ULI	size,
		psio_address	start,
		psio_address *	end
	)

Writes data to a TOC entry in a PSI file.

Parameters:

	unit	= The PSI unit number used to identify the file to all read and write functions.
	key	= The TOC keyword identifying the desired entry.
	buffer	= The buffer from which the data is written.
	size	= The number of bytes to write.
	start	= The entry-relative starting page/offset to write the data.
	end	= A pointer to the entry-relative page/offset for the next byte after the end of the write request.

Definition at line 13 of file write.cc.

References psio_error(), psio_get_address(), psio_get_global_address(), rw(), and tocscan().

Referenced by psio_write(), and rw().

                                                        {
  psio_ud *this_unit;
  psio_tocentry *this_entry, *last_entry;
  psio_address start_toc, start_data, end_data; /* global addresses */
  ULI tocentry_size;
  int dirty = 0;
  
  this_unit = &(psio_unit[unit]);
  
  /* Find the entry in the TOC */
  this_entry = tocscan(unit, key);
  
  tocentry_size = sizeof(psio_tocentry) - 2*sizeof(psio_tocentry *);
  
  if (this_entry == NULL) { /* New TOC entry */
    if (start.page||start.offset)
      psio_error(unit, PSIO_ERROR_BLKSTART);
    
    dirty = 1; /* set flag for writing the TOC header */
    
    this_entry = (psio_tocentry *) malloc(sizeof(psio_tocentry));
    ::strncpy(this_entry->key, key, PSIO_KEYLEN);
    this_entry->key[PSIO_KEYLEN-1] = '\0';
    this_entry->next = NULL;
    this_entry->last = NULL;
    
    /* Compute the global address of the new entry */
    if (!(this_unit->toclen)) { /* First TOC entry */
      this_entry->sadd.page = 0;
      this_entry->sadd.offset = sizeof(ULI); /* offset for the toclen value stored first */
      this_unit->toc = this_entry;
    } else { /* Use ending address from last TOC entry */
      last_entry = toclast(unit);
      this_entry->sadd = last_entry->eadd;
      last_entry->next = this_entry;
      this_entry->last = last_entry;
    }
    
    /* compute important global addresses for the entry */
    start_toc = this_entry->sadd;
    start_data = psio_get_address(start_toc, tocentry_size);
    start_data = psio_get_global_address(start_data, start);
    end_data = psio_get_address(start_data, size);
    
    /* Set the end address for this_entry */
    this_entry->eadd = end_data;
    
    /* Update the unit's TOC stats */
    this_unit->toclen++;
    wt_toclen(unit, this_unit->toclen);
    
    /* Update end (an entry-relative address) for the caller */
    *end = psio_get_address(start, size);
  } else { /* Old TOC entry */
    
    /* Compute the global starting page and offset for the block */
    start_toc = this_entry->sadd;
    start_data = psio_get_address(start_toc, tocentry_size);
    start_data = psio_get_global_address(start_data, start);
    
    /* Make sure this block doesn't start past the end of the entry */
    if (start_data.page > this_entry->eadd.page)
      psio_error(unit, PSIO_ERROR_BLKSTART);
    else if ((start_data.page == this_entry->eadd.page) &&(start_data.offset
        > this_entry->eadd.offset))
      psio_error(unit, PSIO_ERROR_BLKSTART);
    
    /* Compute the new global ending address for the entry, if necessary */
    end_data = psio_get_address(start_data, size);
    if (end_data.page > this_entry->eadd.page) {
      if (this_entry->next != NULL) {
        fprintf(stderr, "PSIO_ERROR: Attempt to write into next entry: %d, %s\n", unit, key);
        psio_error(unit, PSIO_ERROR_BLKEND);
      }
      this_entry->eadd = end_data;
      dirty = 1; /* set flag for writing the TOC header */
    } else if ((end_data.page == this_entry->eadd.page) &&(end_data.offset
        > this_entry->eadd.offset)) {
      if (this_entry->next != NULL) {
        fprintf(stderr, "PSIO_ERROR: Attempt to write into next entry: %d, %s\n", unit, key);
        psio_error(unit, PSIO_ERROR_BLKEND);
      }
      this_entry->eadd = end_data;
      dirty = 1; /* set flag for writing the TOC header */
    }
    
    /* Update end (an entry-relative address) for the caller */
    *end = psio_get_address(start, size);
  }
  
  if (dirty) /* Need to first write/update the TOC header for this record */
    rw(unit, (char *) this_entry, start_toc, tocentry_size, 1);
  
  /* Now write the actual data to the unit */
  rw(unit, buffer, start_data, size, 1);
  
#ifdef PSIO_STATS
  psio_writlen[unit] += size;
#endif
}

---

The documentation for this class was generated from the following files:

• psio.hpp
• libpsio/close.cc
• done.cc
• filescfg.cc
• get_filename.cc
• get_numvols.cc
• get_volpath.cc
• libpsio/init.cc
• open.cc
• open_check.cc
• read.cc
• read_entry.cc
• rw.cc
• tocclean.cc
• toclast.cc
• toclen.cc
• tocprint.cc
• tocread.cc
• tocscan.cc
• tocwrite.cc
• write.cc
• write_entry.cc

---