IOOutput Class Reference

#include <IOOutput.h>

Inheritance diagram for IOOutput:

Public Member Functions
virtual IOSize	write (const void *from, IOSize n)=0
IOSize	write (IOBuffer from)
IOSize	write (unsigned char byte)
virtual IOSize	writev (const IOBuffer *from, IOSize buffers)
IOSize	xwrite (const void *from, IOSize n)
IOSize	xwrite (IOBuffer from)
IOSize	xwritev (const IOBuffer *from, IOSize buffers)
virtual	~IOOutput (void)
	Destruct the stream. A no-op. More...

Detailed Description

Abstract base class for stream-oriented output targets.

Definition at line 7 of file IOOutput.h.

Constructor & Destructor Documentation

~IOOutput()

IOOutput::~IOOutput ( void  )

virtual

Destruct the stream. A no-op.

Definition at line 6 of file IOOutput.cc.

{}

Member Function Documentation

write() [1/3]

IOSize IOOutput::write ( const void *  from, IOSize  n  )

pure virtual

Write n bytes of data starting at address from.

Returns

The number of bytes written. Normally this will be n, but can be less, even zero, for example if the stream is non-blocking mode and cannot accept input at this time.

Exceptions

In	case of error, an exception is thrown. However if the stream is in non-blocking mode and cannot accept output, it will not throw an exception – the return value will be less than requested.

Implemented in XrdFile, File, StorageAccountProxy, DavixFile, DCacheFile, LStoreFile, LocalCacheFile, and IOChannel.

write() [2/3]

IOSize IOOutput::write

(

IOBuffer

from

)

Write to the output stream the buffer from. This method is simply redirected to write(const void *, IOSize).

Note that derived classes should not normally call this method, as it simply routes the call back to derived class through the other virtual functions. Use this method only at the "outside edge" when transferring calls from one object to another, not in up/down calls in the inheritance tree.

Returns

The number of bytes actually written. This is less or equal to the size of the buffer. The value can be less than requested if the stream is unable to accept all the output for platform or implementation reasons.

Exceptions

In	case of error, an exception is thrown. However if the stream is in non-blocking mode and cannot accept output, it will not throw an exception – the return value will be less than requested.

Definition at line 59 of file IOOutput.cc.

{ return write(from.data(), from.size()); }

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

write() [3/3]

IOSize IOOutput::write

(

unsigned char

byte

)

Write a single byte to the output stream. This method is simply redirected to write(const void *, IOSize).

Note that derived classes should not normally call this method, as it simply routes the call back to derived class through the other virtual functions. Use this method only at the "outside edge" when transferring calls from one object to another, not in up/down calls in the inheritance tree.

Returns

The number of bytes written. Normally this will be one, but can be zero if the stream is in non-blocking mode and cannot accept output at this time.

Exceptions

In	case of error, an exception is thrown. However if the stream is in non-blocking mode and cannot accept output, it will not throw an exception – zero will be returned.

Definition at line 39 of file IOOutput.cc.

{ return write(&byte, 1); }

Referenced by write(), writev(), and xwrite().

writev()

IOSize IOOutput::writev ( const IOBuffer *  from, IOSize  buffers  )

virtual

Write to the output stream from multiple buffers. There are buffers to fill in an array starting at from. The buffers are filled in the order given, each buffer fully before the subsequent buffers. The method uses write(const void *, IOSize), but may be implemented more efficiently in derived classes.

Note that derived classes should not normally call this method, as it simply routes the call back to derived class through the other virtual functions. Use this method only at the "outside edge" when transferring calls from one object to another, not in up/down calls in the inheritance tree.

Returns

The number of bytes actually written. This is less or equal to the size of the buffers. The value can be less than requested if the stream is unable to accept all the output for platform or implementation reasons. Note that the return value indicates the number of bytes written, not the number of buffers; it is the sum total of bytes written from all the buffers.

Exceptions

In	case of error, an exception is thrown. However if the stream is in non-blocking mode and cannot accept output, it will not throw an exception – the return value will be less than requested.

Reimplemented in StorageAccountProxy, LocalCacheFile, File, and IOChannel.

Definition at line 84 of file IOOutput.cc.

                                                            {
  assert(!buffers || from);
 
  // Keep writing as long as possible; ignore errors if we have
  // written something, otherwise pass it on.
  IOSize x;
  IOSize done = 0;
  try {
    for (IOSize i = 0; i < buffers; ++i) {
      done += (x = write(from[i].data(), from[i].size()));
      if (x < from[i].size())
        break;
    }
  } catch (cms::Exception &) {
    if (!done)
      throw;
  }
 
  return done;
}

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

xwrite() [1/2]

IOSize IOOutput::xwrite	(	const void *	from,
		IOSize	n
	)

Like the corresponding write() method but writes until the requested number of bytes are written. Writes data from the buffer from for its full size.

Unlike write() which may write less data than requested, this function attempts to write, possibly in multiple write() calls, the exact requested amount of data. It stops writing only in case of error.

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

Note that derived classes should not normally call this method, as it simply routes the call back to derived class through the other virtual functions. Use this method only at the "outside edge" when transferring calls from one object to another, not in up/down calls in the inheritance tree.

Returns

The number of bytes actually written from the buffer, i.e. the size of the buffer.

Exceptions

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

Definition at line 162 of file IOOutput.cc.

                                                  {
  // Keep writing until we've written it all.  Let errors fly over.
  IOSize done = 0;
  while (done < n)
    done += write((const char *)from + done, n - done);
 
  return done;
}

References fileCollector::done, dqmiodumpmetadata::n, and write().

Referenced by xwrite(), and xwritev().

xwrite() [2/2]

IOSize IOOutput::xwrite

(

IOBuffer

from

)

Like the corresponding write() method but writes until the requested number of bytes are written. Writes from contents. This method is redirected to xwrite(const void *, IOSize).

Unlike write() which may write less data than requested, this function attempts to write, possibly in multiple write() calls, the exact requested amount of data. It stops writing only in case of error.

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

Note that derived classes should not normally call this method, as it simply routes the call back to derived class through the other virtual functions. Use this method only at the "outside edge" when transferring calls from one object to another, not in up/down calls in the inheritance tree.

Returns

The number of bytes actually written from the buffer, i.e. the size of the buffer.

Exceptions

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

Definition at line 134 of file IOOutput.cc.

{ return xwrite(from.data(), from.size()); }

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

xwritev()

IOSize IOOutput::xwritev	(	const IOBuffer *	from,
		IOSize	buffers
	)

Like the corresponding writev() method but writes until the requested number of bytes are written. Writes data from buffers starting at from, each for its full size. The buffers are filled in the order given. This method uses xwrite(const void *, IOSize).

Unlike write() which may write less data than requested, this function attempts to write, possibly in multiple write() calls, the exact requested amount of data. It stops writing only in case of error.

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

Note that derived classes should not normally call this method, as it simply routes the call back to derived class through the other virtual functions. Use this method only at the "outside edge" when transferring calls from one object to another, not in up/down calls in the inheritance tree.

Returns

The number of bytes actually written from the buffer, i.e. the size of the buffer.

Exceptions

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

Definition at line 199 of file IOOutput.cc.

                                                             {
  // Keep writing until we've written it all.  Let errors fly over.
  // FIXME: Use writev(from, buffers) and then sort out in case of
  // failure, the writev probably succeed directly with much less
  // overhead.
  assert(!buffers || from);
 
  IOSize done = 0;
  for (IOSize i = 0; i < buffers; ++i)
    done += xwrite(from[i].data(), from[i].size());
 
  return done;
}

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