Libosmium: osmium::io::Writer Class Reference

Libosmium Fast and flexible C++ library for working with OpenStreetMap data

Loading...
Searching...
No Matches
Classes | Public Member Functions | Private Types | Private Member Functions | Static Private Member Functions | Private Attributes | List of all members
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 &&)=delete
Writer & | operator= (Writer &&)=delete
| ~Writer () noexcept
size_t | buffer_size () const noexcept
void | set_buffer_size (size_t size) noexcept
void | set_header (const osmium::io::Header &header)
void | flush ()
void | operator() (osmium::memory::Buffer &&buffer)
void | operator() (const osmium::memory::Item &item)
std::size_t | close ()

## Private Types
enum | { default_buffer_size = 10UL * 1024UL * 1024UL }
enum class | status { okay = 0 , error = 1 , closed = 2 }

## Private Member Functions
void | write_header ()
void | do_write (osmium::memory::Buffer &&buffer)
void | do_flush ()
template<typename TFunction, typename... TArgs>
void | ensure_cleanup (TFunction func, TArgs &&... args)
void | do_close ()

## Static Private Member Functions
static void | write_thread (detail::future_string_queue_type &output_queue, std::unique_ptr< osmium::io::Compressor > &&compressor, std::promise< std::size_t > &&write_promise, std::atomic_bool *notification)
static void | set_option (options_type &options, osmium::thread::Pool &pool)
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 {detail::get_output_queue_size(), "raw_output"}
std::unique_ptr< osmium::io::detail::OutputFormat > | m_output {nullptr}
osmium::memory::Buffer | m_buffer
osmium::io::Header | m_header
size_t | m_buffer_size = default_buffer_size
std::future< std::size_t > | m_write_future
osmium::thread::thread_handler | m_thread
std::atomic_bool | m_notification {false}
enum osmium::io::Writer::status | m_status = status::okay
bool | m_header_written = false

## 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

## ◆ anonymous enum

anonymous enum
| private

Enumerator
default_buffer_size |

## ◆ status

enum class osmium::io::Writer::status
| strongprivate

Enumerator
okay |
error |
closed |

## Constructor & Destructor Documentation

## ◆ Writer() [1/5]

template<typename... TArgs>

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

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).
- osmium::thread::Pool&: Reference to a thread pool that should be used for writing instead of the default pool. Usually it is okay to use the statically initialized shared default pool, but sometimes you want or need your own. For instance when your program will fork, using the statically initialized pool will not work.

Exceptions

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

## ◆ Writer() [2/5]

template<typename... TArgs>

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

## ◆ Writer() [3/5]

template<typename... TArgs>

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

## ◆ Writer() [4/5]

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

## ◆ Writer() [5/5]

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

## ◆ ~Writer()

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

## Member Function Documentation

## ◆ buffer_size()

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

Get the currently configured size of the internal buffer.

## ◆ close()

std::size_t 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.

Returns
  Number of bytes written to the file (or 0 if it can not be determined).

Exceptions

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

## ◆ do_close()

void osmium::io::Writer::do_close | ( |  | ) |
| inlineprivate

## ◆ do_flush()

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

## ◆ do_write()

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

## ◆ ensure_cleanup()

template<typename TFunction, typename... TArgs>

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

## ◆ flush()

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.

## ◆ operator()() [1/2]

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.

## ◆ operator()() [2/2]

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.

## ◆ operator=() [1/2]

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

## ◆ operator=() [2/2]

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

## ◆ set_buffer_size()

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

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

## ◆ set_header()

void osmium::io::Writer::set_header | ( | const osmium::io::Header & | header | ) |
| inline

Set header. This will overwrite a header set in the constructor.

Has to be called before writing anything to the file, otherwise this will not do anything.

## ◆ set_option() [1/4]

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

## ◆ set_option() [2/4]

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

## ◆ set_option() [3/4]

void osmium::io::Writer::set_option | ( | options_type & | options,
|  | osmium::thread::Pool & | pool )
| inlinestaticprivate

## ◆ set_option() [4/4]

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

## ◆ write_header()

void osmium::io::Writer::write_header | ( |  | ) |
| inlineprivate

## ◆ write_thread()

void osmium::io::Writer::write_thread | ( | detail::future_string_queue_type & | output_queue,
|  | std::unique_ptr< osmium::io::Compressor > && | compressor,
|  | std::promise< std::size_t > && | write_promise,
|  | std::atomic_bool * | notification )
| inlinestaticprivate

## Member Data Documentation

## ◆ m_buffer

osmium::memory::Buffer osmium::io::Writer::m_buffer
| private

## ◆ m_buffer_size

size_t osmium::io::Writer::m_buffer_size = default_buffer_size
| private

## ◆ m_file

osmium::io::File osmium::io::Writer::m_file
| private

## ◆ m_header

osmium::io::Header osmium::io::Writer::m_header
| private

## ◆ m_header_written

bool osmium::io::Writer::m_header_written = false
| private

## ◆ m_notification

std::atomic_bool osmium::io::Writer::m_notification {false}
| private

## ◆ m_output

std::unique_ptr<osmium::io::detail::OutputFormat> osmium::io::Writer::m_output {nullptr}
| private

## ◆ m_output_queue

detail::future_string_queue_type osmium::io::Writer::m_output_queue {detail::get_output_queue_size(), "raw_output"}
| private

## ◆ m_status

enum osmium::io::Writer::status osmium::io::Writer::m_status = status::okay
| private

## ◆ m_thread

osmium::thread::thread_handler osmium::io::Writer::m_thread
| private

## ◆ m_write_future

std::future<std::size_t> osmium::io::Writer::m_write_future
| private

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

- include/osmium/io/writer.hpp