---

IOInput Class Reference

Abstract base class for stream-oriented input sources. More...

#include <Utilities/StorageFactory/interface/IOInput.h>

Inheritance diagram for IOInput:

List of all members.

Public Member Functions
virtual IOSize	read (void *into, IOSize n)=0
	Read into into at most n number of bytes.
IOSize	read (IOBuffer into)
	Read from the input stream into the buffer starting at into and of size n.
int	read (void)
	Read the next single byte from the input stream and return it as an unsigned char cast to an int, -1 to indicate end of intput data.
virtual IOSize	readv (IOBuffer *into, IOSize buffers)
	Read from the input stream into multiple scattered buffers.
IOSize	xread (void *into, IOSize n)
	Like the corresponding read() method but reads until the requested number of bytes are read or end of file is reached.
IOSize	xread (IOBuffer into)
	Like the corresponding read() method but reads until the requested number of bytes are read or end of file is reached.
IOSize	xreadv (IOBuffer *into, IOSize buffers)
	Like the corresponding readv() method but reads until the requested number of bytes are read or end of file is reached.
virtual	~IOInput (void)
	Destruct the stream. A no-op.

---

Detailed Description

Abstract base class for stream-oriented input sources.

Definition at line 7 of file IOInput.h.

---

Constructor & Destructor Documentation

IOInput::~IOInput

(

void

)

[virtual]

Destruct the stream. A no-op.

Definition at line 6 of file IOInput.cc.

{}

---

Member Function Documentation

IOSize IOInput::read	(	void *	into,
		IOSize	n
	)			[pure virtual]

Read into into at most n number of bytes.

If this is a blocking stream, the call will block until some data can be read, end of input is reached, or an exception is thrown. For a non-blocking stream the available input is returned. If none is available, an exception is thrown.

Returns:

The number of bytes actually read. This is less or equal to the size of the buffer. Zero indicates that the end of the input has been reached: end of file, or remote end closing for a connected channel like a pipe or a socket. Otherwise the value can be less than requested if limited amount of input is currently available for platform or implementation reasons.

Exceptions:

In

case of error, a IOError exception is thrown. This includes the situation where the input stream is in non-blocking mode and no input is currently available (FIXME: make this simpler; clarify which exception).

Implemented in DCacheFile, RFIOFile, File, IOChannel, LocalCacheFile, StorageAccountProxy, and XrdFile.

IOSize IOInput::read

(

IOBuffer

into

)

Read from the input stream into the buffer starting at into and of size n.

If this is a blocking stream, the call will block until some data can be read, end of input is reached, or an exception is thrown. For a non-blocking stream the available input is returned. If none is available, an exception is thrown.

The base class implementation simply forwards the call to read(void *, IOSize) method.

Returns:

The number of bytes actually read. This is less or equal to the size of the buffer. Zero indicates that the end of the input has been reached: end of file, or remote end closing for a connected channel like a pipe or a socket. Otherwise the value can be less than requested if limited amount of input is currently available for platform or implementation reasons.

Exceptions:

In

case of error, a IOError exception is thrown. This includes the situation where the input stream is in non-blocking mode and no input is currently available (FIXME: make this simpler; clarify which exception).

Definition at line 84 of file IOInput.cc.

References IOBuffer::data(), read(), and IOBuffer::size().

{ return read (into.data (), into.size ()); }

int IOInput::read

(

void

)

Read the next single byte from the input stream and return it as an unsigned char cast to an int, -1 to indicate end of intput data.

If this is a blocking stream, the call will block until the byte can be read, end of data is reached, or an exception is thrown. For a non-blocking input a character is returned if one is available, otherwise an exception is thrown.

The base class implementation simply forwards the call to read(void *, IOSize) method.

Returns:

The byte cast from a unsigned char to an int (in range 0...255, inclusive) if one could be read, or -1 to indicate end of input data.

Exceptions:

In

case of error, a IOError exception is thrown. This includes the situation where the input stream is in non-blocking mode and no input is currently available (FIXME: make this simpler; clarify which exception).

Definition at line 54 of file IOInput.cc.

References n.

Referenced by IOChannel::read(), read(), File::read(), Storage::read(), readv(), Storage::readv(), and xread().

{
  unsigned char byte;
  IOSize n = read (&byte, 1);
  return n == 0 ? -1 : byte;
}

IOSize IOInput::readv	(	IOBuffer *	into,
		IOSize	buffers
	)			[virtual]

Read from the input stream into multiple scattered buffers.

There are buffers to fill in an array starting at into; the memory those buffers occupy does not need to be contiguous. The buffers are filled in the order given, eac buffer is filled fully before the subsequent buffers.

If this is a blocking stream, the call will block until some data can be read, end of input is reached, or an exception is thrown. For a non-blocking stream the available input is returned. If none is available, an exception is thrown.

The base class implementation uses read(void *, IOSize) method, but derived classes may implement a more efficient alternative.

Returns:

The number of bytes actually read. This is less or equal to the size of the buffer. Zero indicates that the end of the input has been reached: end of file, or remote end closing for a connected channel like a pipe or a socket. Otherwise the value can be less than requested if limited amount of input is currently available for platform or implementation reasons. Note that the return value indicates the number of bytes read, not the number of buffers; it is the sum total of bytes filled into all the buffers.

Exceptions:

In

case of error, a IOError exception is thrown. However if some data has already been read, the error is swallowed and the method returns the data read so far. It is assumed that persistent errors will occur anyway on the next read and sporadic errors like stream becoming unvailable can be ignored. Use xread() if a different policy is desirable.

Reimplemented in File, IOChannel, LocalCacheFile, StorageAccountProxy, and XrdFile.

Definition at line 117 of file IOInput.cc.

References i, read(), and StDecayID::status.

{
  assert (! buffers || into);

  // Keep reading as long as possible; ignore errors if we have read
  // something, otherwise pass it on.
  IOSize status;
  IOSize done = 0;
  try
  {
    for (IOSize i = 0; i < buffers; done += status, ++i)
      if ((status = read (into [i])) == 0)
        break;
  }
  catch (cms::Exception &)
  {
    if (! done)
      throw;
  }

  return done;
}

IOSize IOInput::xread	(	void *	into,
		IOSize	n
	)

Like the corresponding read() method but reads until the requested number of bytes are read or end of file is reached.

Reads data into the buffer into for its full size.

Unlike read() which may return less data than requested, this function attempts to read, possibly in multiple read() calls, the exact requested amount of data. It stops reading only if it reaches the end of the input stream (i.e., read() returns zero).

If the you know the stream blocks on read() and it would be inconvenient to handle partial read() results, use this method as a convenience for hiding platforms and circumstance differences. It makes no sense to use this method with non-blocking input.

Returns:

The number of bytes actually read into the buffer, i.e. the size of the buffer. It will be less only if the end of the file has been reached.

Exceptions:

All

exceptions from read() are passed through unhandled. Therefore it is possible that an exception is thrown when this function has already read some data.

Definition at line 191 of file IOInput.cc.

References read(), and x.

{
  assert (into);

  // Keep reading as long as possible.  Let system errors fly over
  // us, they are a hard error.
  IOSize x;
  IOSize done = 0;
  while (done < n && (x = read ((char *) into + done, n - done)))
    done += x;

  return done;
}

IOSize IOInput::xread

(

IOBuffer

into

)

Like the corresponding read() method but reads until the requested number of bytes are read or end of file is reached.

Reads n bytes of data into the buffer into. This method is simply redirected to xread(void *, IOSize).

Unlike read() which may return less data than requested, this function attempts to read, possibly in multiple read() calls, the exact requested amount of data. It stops reading only if it reaches the end of the input stream (i.e., read() returns zero).

If the you know the stream blocks on read() and it would be inconvenient to handle partial read() results, use this method as a convenience for hiding platforms and circumstance differences. It makes no sense to use this method with non-blocking input.

Returns:

The number of bytes actually read into the buffer, i.e. the size of the buffer. It will be less only if the end of the file has been reached.

Exceptions:

All

exceptions from read() are passed through unhandled. Therefore it is possible that an exception is thrown when this function has already read some data.

Definition at line 166 of file IOInput.cc.

References IOBuffer::data(), and IOBuffer::size().

Referenced by TStorageFactoryFile::ReadBuffer(), and xreadv().

{ return xread (into.data (), into.size ()); }

IOSize IOInput::xreadv	(	IOBuffer *	into,
		IOSize	buffers
	)

Like the corresponding readv() method but reads until the requested number of bytes are read or end of file is reached.

Reads data into buffers starting at into, each for its full size. The buffers are filled in the order given. This method uses xread(void *, IOSize).

Unlike readv() which may return less data than requested, this function attempts to read, possibly in multiple read() calls, the exact requested amount of data. It stops reading only if it reaches the end of the input stream (i.e., read() returns zero).

If the you know the stream blocks on read() and it would be inconvenient to handle partial read() results, use this method as a convenience for hiding platforms and circumstance differences. It makes no sense to use this method with non-blocking input.

Returns:

The number of bytes actually read into the buffer, i.e. the size of the buffer. It will be less only if the end of the file has been reached.

Exceptions:

All

exceptions from read() are passed through unhandled. Therefore it is possible that an exception is thrown when this function has already read some data.

Definition at line 229 of file IOInput.cc.

References i, size, x, and xread().

{
  // FIXME: Use read(into, buffers) and then sort out in case of
  // failure, the readv probably succeed directly with much less
  // overhead.

  assert (! buffers || into);

  // Keep reading as long as possible.  Let system errors fly
  // over us, they are a hard error.
  IOSize x;
  IOSize done = 0;
  for (IOSize i = 0; i < buffers; ++i)
  {
    done += (x = xread (into [i]));
    if (x < into [i].size ())
      break;
  }
  return done;
}

---

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

• Utilities/StorageFactory/interface/IOInput.h
• Utilities/StorageFactory/src/IOInput.cc

---