nlib
nn::nlib::OutputStream Class Referenceabstract

The base class for output streams. This class cannot be instantiated. More...

#include "nn/nlib/OutputStream.h"

+ Inheritance diagram for nn::nlib::OutputStream:

Public Types

enum  BufferingMode {
  BUFFERINGMODE_BLOCKBUFFERED = 0,
  BUFFERINGMODE_LINEBUFFERED,
  BUFFERINGMODE_UNBUFFERED
}
 The buffering mode for OutputStream. More...
 

Public Member Functions

size_t Pos () const noexcept
 Returns the current position in the stream. More...
 
uint64_t Pos64 () const noexcept
 Returns the current position in the stream as a 64-bit integer. More...
 
bool Write (int b) noexcept
 Writes one byte of data to the stream. More...
 
bool Write (const void *p, size_t n) noexcept
 Writes n bytes of data to the stream. More...
 
bool WriteGather (const nlib_fd_iovec *iov, int iovcnt) noexcept
 Writes data from multiple non-continuous buffers to a stream. More...
 
bool Flush () noexcept
 Flushes the stream. More...
 
bool Close () noexcept
 Closes the stream after it has been flushed. Returns true if successful. More...
 
errno_t GetErrorValue () const noexcept
 Gets the error value. More...
 
BufferingMode GetBufferingMode () const noexcept
 Gets the buffering mode.
 
 operator bool () const
 Returns true if no internal error has occurred.
 
Basic Member Functions
constexpr OutputStream () noexcept
 Instantiates the object with default parameters (default constructor).
 
virtual ~OutputStream () noexcept
 Destructor. Does not do anything.
 

Functions Used From Derived Classes

BufferingMode m_BufferingMode
 Stores the buffering mode. More...
 
void ResetBuffer (void *p, size_t nbytes) noexcept
 Sets the buffer held by OutputStream. More...
 
void SetError (errno_t e) const noexcept
 Sets an error to OutputStream. More...
 

Detailed Description

The base class for output streams. This class cannot be instantiated.

Description
It is the base class for output streams with a synchronous and sequential access interface. The place where the data is written is defined by the derived class.

Information for Implementing Derived Classes

The specifications for the OutputStream class may change without notice. You can lower your risk by implementing derived classes independently whenever possible. However, if necessary, you can define derived classes by overriding the following virtual function.
bool PushBuffer_(const void* p, size_t nbytes, bool do_flush)
p is the pointer to the data to write to the device, and nBytes is the size. If doFlush is true, the device must be flushed.
If the buffer has not yet been configured by the GetWorkBuffer_ function (described below), you can call this function with NULL specified for the p parameter. If you do that, you need to call the ResetBuffer function and reset the OutputStream internal buffer.
In the case of errors, deal with them as shown in the examples below.
  • If there is no compatible device (for example, the handle is invalid), set the EBADF error and return false.
  • If there is a confirmed failure while writing, set an error (for example, EIO) and return false.
bool Close_()
Called from the Close function to close handles and other internal resources. At the time that the Close function is called, the buffer referenced by the base class is guaranteed to have been emptied by the PushBuffer_ function. If the derived class has a different buffer than this, you must close the device after the data has been actually written to the device.
In either case, you must free all internally held resources. Be careful not to call the Close_ function from the base class destructor.
In the case of errors, deal with them as shown in the examples below.
  • If there is no compatible device (for example, the handle is invalid), set the EBADF error and return false.
  • If the process fails during flushing while closing, set some error (for example, EIO) and return false.
Note that even if an error occurs, you must make sure that the handle and other internal resources are freed.
outGetWorkBuffer void* GetWorkBuffer_(size_t* nbytes)
If is_buf_ is NULL, OutputStream calls this function to try to get a buffer. The return value is the pointer to the buffer. The size gets set in nBytes. The buffer itself is owned by the derived class, so the freeing of the buffer must be coded in the derived class.
If memory fails to be allocated and no buffer is passed, you must return NULL and set nBytes to 0.
If you do not override this function, it returns NULL and -1 is substituted for the value in nBytes. In that case, InputStream uses the FillBuffer_ function to try to get a buffer.

Definition at line 17 of file OutputStream.h.

Member Enumeration Documentation

§ BufferingMode

The buffering mode for OutputStream.

Enumerator
BUFFERINGMODE_BLOCKBUFFERED 

The output is block buffered. This is the default.

BUFFERINGMODE_LINEBUFFERED 

The output is line buffered. This mode is set when data is output to the console.

BUFFERINGMODE_UNBUFFERED 

The output is not buffered.

Definition at line 19 of file OutputStream.h.

Member Function Documentation

§ Close()

nn::nlib::OutputStream::Close ( )
noexcept

Closes the stream after it has been flushed. Returns true if successful.

Returns
Returns true when successful.
Description
If the function returns false, a process failed. Even if a process fails, you do not need to close again. If already successfully closed, the function returns true.
Examples:
misc/stringutils/stringutils.cpp.

§ Flush()

nn::nlib::OutputStream::Flush ( )
inlinenoexcept

Flushes the stream.

Returns
Returns true when successful.
Description
All buffered data is written to the stream.

Definition at line 85 of file OutputStream.h.

§ GetErrorValue()

nn::nlib::OutputStream::GetErrorValue ( ) const
inlinenoexcept

Gets the error value.

Returns
Returns the error value.

Definition at line 87 of file OutputStream.h.

§ Pos()

nn::nlib::OutputStream::Pos ( ) const
inlinenoexcept

Returns the current position in the stream.

Returns
The current position in the stream (the number of bytes that have been written).

Definition at line 38 of file OutputStream.h.

§ Pos64()

nn::nlib::OutputStream::Pos64 ( ) const
inlinenoexcept

Returns the current position in the stream as a 64-bit integer.

Returns
The current position in the stream (the number of bytes that have been written).

Definition at line 39 of file OutputStream.h.

§ ResetBuffer()

nn::nlib::OutputStream::ResetBuffer ( void *  p,
size_t  nbytes 
)
inlineprotectednoexcept

Sets the buffer held by OutputStream.

Parameters
[in]pPointer to the buffer.
[in]nbytesBuffer size.

Definition at line 94 of file OutputStream.h.

§ SetError()

nn::nlib::OutputStream::SetError ( errno_t  e) const
inlineprotectednoexcept

Sets an error to OutputStream.

Parameters
[in]eAn error value.

Definition at line 98 of file OutputStream.h.

§ Write() [1/2]

nn::nlib::OutputStream::Write ( int  b)
inlinenoexcept

Writes one byte of data to the stream.

Parameters
[in]bThe data to write.
Returns
Returns true when successful.
Examples:
misc/stringutils/stringutils.cpp.

Definition at line 40 of file OutputStream.h.

§ Write() [2/2]

nn::nlib::OutputStream::Write ( const void *  p,
size_t  n 
)
inlinenoexcept

Writes n bytes of data to the stream.

Parameters
[in]pPointer to the data to write.
[in]nThe number of bytes.
Returns
Returns true when successful.

Definition at line 54 of file OutputStream.h.

§ WriteGather()

nn::nlib::OutputStream::WriteGather ( const nlib_fd_iovec *  iov,
int  iovcnt 
)
inlinenoexcept

Writes data from multiple non-continuous buffers to a stream.

Parameters
[in]iovPointers to iovcnt number of buffers and the corresponding sizes.
[in]iovcntThe number of iov.
Returns
Returns true when successful.
Description
When using FileOutputStream, this member function may write the data from the buffers one by one in order to speed up the write process. However, the write process is not guaranteed to be performed atomically, as it is when using the nlib_fd_writev function.

Definition at line 72 of file OutputStream.h.

Member Data Documentation

§ m_BufferingMode

nn::nlib::OutputStream::m_BufferingMode
protected

Stores the buffering mode.

Description
If a non-zero error has been set already, that error value is not overwritten.

Definition at line 126 of file OutputStream.h.


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