osmium::io::Writer Class Reference

`#include <writer.hpp>`

Collaboration diagram for osmium::io::Writer:
[legend]

## Classes

struct | options_type

## Public Member Functions

template<typename... TArgs>
| Writer (const osmium::io::File &file, TArgs &&...args)
template<typename... TArgs>
| Writer (const std::string &filename, TArgs &&...args)
template<typename... TArgs>
| Writer (const char *filename, TArgs &&...args)
| Writer (const Writer &)=delete
Writer & | operator= (const Writer &)=delete
| Writer (Writer &&)=default
Writer & | operator= (Writer &&)=default
| ~Writer () noexcept
size_t | buffer_size () const noexcept
void | set_buffer_size (size_t size) noexcept
void | flush ()
void | operator() (osmium::memory::Buffer &&buffer)
void | operator() (const osmium::memory::Item &item)
void | close ()

## Private Types

enum | status { status::okay = 0, status::error = 1, status::closed = 2 }

## Private Member Functions

void | do_write (osmium::memory::Buffer &&buffer)
void | do_flush ()
template<typename TFunction , typename... TArgs>
void | ensure_cleanup (TFunction func, TArgs &&...args)

## Static Private Member Functions

static void | write_thread (detail::future_string_queue_type &output_queue, std::unique_ptr< osmium::io::Compressor > &&compressor, std::promise< bool > &&write_promise)
static void | set_option (options_type &options, const osmium::io::Header &header)
static void | set_option (options_type &options, overwrite value)
static void | set_option (options_type &options, fsync value)

## Private Attributes

osmium::io::File | m_file
detail::future_string_queue_type | m_output_queue
std::unique_ptr< osmium::io::detail::OutputFormat > | m_output
osmium::memory::Buffer | m_buffer
size_t | m_buffer_size
std::future< bool > | m_write_future
osmium::thread::thread_handler | m_thread
enum osmium::io::Writer::status | m_status

## Static Private Attributes

static constexpr size_t | default_buffer_size = 10 * 1024 * 1024

## Detailed Description

This is the user-facing interface for writing OSM files. Instantiate an object of this class with a file name or osmium::io::File object and optionally the data for the header and then call operator() on it to write Buffers or Items.

The writer uses multithreading internally to do the actual encoding of the data into the intended format, possible compress the data and then write it out. But this is intentionally hidden from the user of this class who can use it without knowing those details.

If you are done call the close() method to finish up. Only if you don't get an exception from the close() method, you can be sure the data is written correctly (modulo operating system buffering). The destructor of this class will also do the right thing if you forget to call close(), but because the destructor can't throw you will not get informed about any problems.

The writer is usually used to write complete blocks of data stored in osmium::memory::Buffers. But you can also write single osmium::memory::Items. In this case the Writer uses an internal Buffer.

## Member Enumeration Documentation

enum osmium::io::Writer::status

strong private

Enumerator
okay |
error |
closed |

## Constructor & Destructor Documentation

template<typename... TArgs>

osmium::io::Writer::Writer | ( | const osmium::io::File & | file,
|  | TArgs &&... | args
| ) |  |

inline explicit

The constructor of the Writer object opens a file and writes the header to it.

Parameters

  file | File (contains name and format info) to open.
  args | All further arguments are optional and can appear in any order:

- osmium::io::Header: Optional header data. If this is not given, a default constructed osmium::io::Header object will be used.
- osmium::io::overwrite: Allow overwriting of existing file? Can be osmium::io::overwrite::allow or osmium::io::overwrite::no (default).
- osmium::io::fsync: Should fsync be called on the file before closing it? Can be osmium::io::fsync::yes or osmium::io::fsync::no (default).

Exceptions

  osmium::io_error | If there was an error.
  std::system_error | If the file could not be opened.

template<typename... TArgs>

osmium::io::Writer::Writer | ( | const std::string & | filename,
|  | TArgs &&... | args
| ) |  |

inline explicit

template<typename... TArgs>

osmium::io::Writer::Writer | ( | const char * | filename,
|  | TArgs &&... | args
| ) |  |

inline explicit

osmium::io::Writer::Writer | ( | const Writer & |  | ) |

delete

osmium::io::Writer::Writer | ( | Writer && |  | ) |

default

osmium::io::Writer::~Writer | ( |  | ) |

inline noexcept

## Member Function Documentation

size_t osmium::io::Writer::buffer_size | ( |  | ) | const

inline noexcept

Get the currently configured size of the internal buffer.

void osmium::io::Writer::close | ( |  | ) |

inline

Flushes internal buffer and closes output file. If you do not call this, the destructor of Writer will also do the same thing. But because this call might throw an exception, which the destructor will ignore, it is better to call close() explicitly.

Exceptions

  Some | form of osmium::io_error when there is a problem.

void osmium::io::Writer::do_flush | ( |  | ) |

inline private

void osmium::io::Writer::do_write | ( | osmium::memory::Buffer && | buffer | ) |

inline private

template<typename TFunction , typename... TArgs>

void osmium::io::Writer::ensure_cleanup | ( | TFunction | func,
|  | TArgs &&... | args
| ) |  |

inline private

void osmium::io::Writer::flush | ( |  | ) |

inline

Flush the internal buffer if it contains any data. This is usually not needed as the buffer gets flushed on close() automatically.

Exceptions

  Some | form of osmium::io_error when there is a problem.

void osmium::io::Writer::operator() | ( | osmium::memory::Buffer && | buffer | ) |

inline

Write contents of a buffer to the output file. The buffer is moved into this function and will be in an undefined moved-from state afterwards.

Parameters

  buffer | Buffer that is being written out.

Exceptions

  Some | form of osmium::io_error when there is a problem.

void osmium::io::Writer::operator() | ( | const osmium::memory::Item & | item | ) |

inline

Add item to the internal buffer for eventual writing to the output file.

Parameters

  item | Item to write (usually an OSM object).

Exceptions

  Some | form of osmium::io_error when there is a problem.

Writer& osmium::io::Writer::operator= | ( | const Writer & |  | ) |

delete

Writer& osmium::io::Writer::operator= | ( | Writer && |  | ) |

default

void osmium::io::Writer::set_buffer_size | ( | size_t | size | ) |

inline noexcept

Set the size of the internal buffer. This will only take effect if you have not yet written anything or after the next flush().

static void osmium::io::Writer::set_option | ( | options_type & | options,
|  | const osmium::io::Header & | header
| ) |  |

inline static private

static void osmium::io::Writer::set_option | ( | options_type & | options,
|  | overwrite | value
| ) |  |

inline static private

static void osmium::io::Writer::set_option | ( | options_type & | options,
|  | fsync | value
| ) |  |

inline static private

static void osmium::io::Writer::write_thread | ( | detail::future_string_queue_type & | output_queue,
|  | std::unique_ptr< osmium::io::Compressor > && | compressor,
|  | std::promise< bool > && | write_promise
| ) |  |

inline static private

## Member Data Documentation

constexpr size_t osmium::io::Writer::default_buffer_size = 10 * 1024 * 1024

static private

osmium::memory::Buffer osmium::io::Writer::m_buffer

private

size_t osmium::io::Writer::m_buffer_size

private

osmium::io::File osmium::io::Writer::m_file

private

std::unique_ptr<osmium::io::detail::OutputFormat> osmium::io::Writer::m_output

private

detail::future_string_queue_type osmium::io::Writer::m_output_queue

private

enum osmium::io::Writer::status osmium::io::Writer::m_status

private

osmium::thread::thread_handler osmium::io::Writer::m_thread

private

std::future<bool> osmium::io::Writer::m_write_future

private

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

- osmium/io/writer.hpp