IOInput Class Reference

#include <IOInput.h>

Inheritance diagram for IOInput:

Public Member Functions
IOSize	read (IOBuffer into)
virtual IOSize	read (void *into, IOSize n)=0
int	read (void)
virtual IOSize	readv (IOBuffer *into, IOSize buffers)
IOSize	xread (IOBuffer into)
IOSize	xread (void *into, IOSize n)
IOSize	xreadv (IOBuffer *into, IOSize buffers)
virtual	~IOInput (void)
	Destruct the stream. A no-op. More...

Detailed Description

Abstract base class for stream-oriented input sources.

Definition at line 7 of file IOInput.h.

Constructor & Destructor Documentation

~IOInput()

IOInput::~IOInput ( void  )

virtual

Destruct the stream. A no-op.

Definition at line 6 of file IOInput.cc.

{}

Member Function Documentation

read() [1/3]

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 80 of file IOInput.cc.

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

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

read() [2/3]

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 XrdFile, File, StorageAccountProxy, DavixFile, DCacheFile, LStoreFile, LocalCacheFile, and IOChannel.

read() [3/3]

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 52 of file IOInput.cc.

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

References dqmiodumpmetadata::n.

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

readv()

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 XrdFile, StorageAccountProxy, LocalCacheFile, File, DavixFile, DCacheFile, and IOChannel.

Definition at line 111 of file IOInput.cc.

                                                    {
  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;
}

References cms::cuda::assert(), fileCollector::done, mps_fire::i, read(), and mps_update::status.

xread() [1/2]

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 155 of file IOInput.cc.

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

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

Referenced by xreadv().

xread() [2/2]

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 178 of file IOInput.cc.

                                          {
  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;
}

References cms::cuda::assert(), fileCollector::done, dqmiodumpmetadata::n, read(), and x.

xreadv()

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 214 of file IOInput.cc.

                                                     {
  // 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;
}

References cms::cuda::assert(), fileCollector::done, mps_fire::i, findQualityFiles::size, x, and xread().