Function Template close

Description
When is close invoked?
Headers
Reference

Description

The Iostreams library provides three overloads of the function template close.

The first overload of close takes a single Device argument. It allows a user to close a Device without worrying whether the Device controls a single sequence or two sequences:

namespace boost { namespace iostreams {
              
template<typename T>     
void close(T& t);

} } // End namespace boost::io

The other two overloads of close should rarely be called by library users; they are invoked automatically by the library to indicate to Filters and Devices that a sequence of data is about to end. This gives Filters and Devices an opportunity to free resources or to reset their states in preparation for a new character sequence. Filters and Devices which perform output can use the opportunity to write additional data to the end of a stream.

The details regarding when and how close is invoked are a bit messy:

When is close invoked?

stream_buffer and stream

When an instance of stream_buffer or stream based on a Device d is closed using member function close, the following sequence of functions calls is made:

    boost::iostreams::close(d, std::ios_base::in);
    boost::iostreams::close(d, std::ios_base::out);

The effect, if D is Closable and controls a single sequence, is as follows:

    d.close();

If D is Closable and controls separate input and output sequences, the effect is as follows:

    d.close(std::ios_base::in);
    d.close(std::ios_base::out);

(See the semantics of close for Device types, below.)

filtering_streambuf and filtering_stream

A filtering_streambuf or filtering_stream is considered to be closed if its lifetime ends while its chain is complete or if its terminal Device is removed using pop or reset. When this occurs, the following sequence of calls is made, assuming that the underlying sequence of Filters and Devices is f1, f1, ..., fn-1, d and the corresponding sequence of stream buffers is buf1, buf2, ..., bufn-1, bufn:[1]

    using namespace std;
    
    // Close each input sequence, in reverse order:
    boost::iostreams::close(d,n-1, bufn-1 ios_base::in);
    boost::iostreams::close(fn-1, bufn,-1 ios_base::in);
    boost::iostreams::close(fn-2, bufn-1, ios_base::in);
    ...
    boost::iostreams::close(f1,n- buf2,n- ios_base::in);

    // Close each output sequence, in order:
    boost::iostreams::close(f1,n- buf2,n- ios_base::out);
    boost::iostreams::close(f2,n- buf3,n- ios_base::out);
    ...
    boost::iostreams::close(fn-1, bufn,n- ios_base::out);
    boost::iostreams::close(d,n-1, bufn-1 ios_base::out);

This implies

(See the semantics of close for Filter and Device types, below.)

Headers

<boost/iostreams/close.hpp>
<boost/iostreams/operations.hpp>

Reference

Synopsis

namespace boost { namespace iostreams {
              
template<typename T>     
void close(T& t);
              
template<typename T>     
void close(T& t, std::ios_base::openmode which);

template<typename T, typename Device>
void close(T& t, Device& next, std::ios_base::openmode which);

} } // End namespace boost::io

Function Template close — Convenience Function

Template Parameters

T- A model of one of the Device concepts.

Semantics

template<typename T>     
void close(T& t);

This overload of close calls close(t, std::ios_base::in) followed by close(t, std::ios_base::out). It ensures that t is closed properly, regardless of the mode or t.

Function Template close — Closure Notification for Devices

Template Parameters

T- A model of one of the Device concepts.

Semantics

template<typename T>     
void close(T& t, std::ios_base::openmode which);

If t is a filtering stream or stream buffer, close calls pop if t is complete. The semantics depends on its category as follows:

category<T>::typesemantics
convertible to input but not to output calls t.pop() if t is complete and which == ios_base::in
otherwise calls t.pop() if t is complete and which == ios_base::out

The semantics of close for a device T other than a filtering stream or stream buffer depends on its category as follows:

category<T>::typesemantics
not convertible to closable_tag calls flush
convertible to closable_tag and to bidirectional calls t.close(which)
convertible to closable_tag and to input but not to output calls t.close() if which == ios_base::in
convertible to closable_tag and to output but not to bidirectional calls t.close() if which == ios_base::out

In short:

The last condition prevents a Device controlling a single sequence from being closed twice in succession.

NOTE: Starting with Boost 1.35, the invocation of this function with an openmode other than std::ios_base::in or std::ios_base::out is deprecated. To close both sequences at once, use

close(t)
instead of
close(t, std::ios_base::in | std::ios_base::out)

Function Template close — Closure Notification for Filters

Template Parameters

T- A model of one of the Filter concepts
Device- A Blocking Device whose mode refines that of T.

Semantics

template<typename T, typename Device>
void close(T& t, Device& next, std::ios_base::openmode which);

The semantics of close for a Filter type T depends on its category as follows:

category<T>::typesemantics
not convertible to closable_tag calls flush
convertible to closable_tag and to bidirectional calls t.close(next, which)
convertible to closable_tag and to input but not to output calls t.close(next) if which == ios_base::in
convertible to closable_tag and to output but not to bidirectional calls t.close(next) if which == ios_base::out

In short:

The last condition prevents a Filter controlling a single sequence from being closed twice in succession.

NOTE: Starting with Boost 1.35, the invocation of this function with an openmode other than std::ios_base::in or std::ios_base::out is deprecated.


[1]This behavior can be disabled in the case of pop by calling member function set_auto_close with the argument false. See, e.g., filtering_stream::set_auto_close.