osmium::io::Writer Class Reference

#include <writer.hpp>

Collaboration diagram for osmium::io::Writer:

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]

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

inlinestaticprivate

set_option() [2/4]

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

inlinestaticprivate

set_option() [3/4]

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

inlinestaticprivate

set_option() [4/4]

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

inlinestaticprivate

write_header()

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

inlineprivate

write_thread()

static 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