llfio_v2_xxx::algorithm::combining_handle_adapter< Op, Target, Source > Class Template Reference

A handle combining the data from one or two other handles. More...

#include "combining.hpp"

Inheritance diagram for llfio_v2_xxx::algorithm::combining_handle_adapter< Op, Target, Source >:

Public Types
using	path_type = byte_io_handle::path_type
using	extent_type = byte_io_handle::extent_type
using	size_type = byte_io_handle::size_type
using	mode = byte_io_handle::mode
using	creation = byte_io_handle::creation
using	caching = byte_io_handle::caching
using	flag = byte_io_handle::flag
using	buffer_type = byte_io_handle::buffer_type
using	const_buffer_type = byte_io_handle::const_buffer_type
using	buffers_type = byte_io_handle::buffers_type
using	const_buffers_type = byte_io_handle::const_buffers_type
template<class T >
using	io_request = byte_io_handle::io_request< T >
template<class T >
using	io_result = byte_io_handle::io_result< T >
using	target_handle_type = Target
using	source_handle_type = Source

Public Member Functions
	combining_handle_adapter ()=default
	Default constructor.
template<class... Args>
	combining_handle_adapter (target_handle_type *a, source_handle_type *b, mode _mode=mode::write, flag flags=flag::none, byte_io_multiplexer *ctx=nullptr, Args &&...args)
	Constructor, passing any extra arguments to Op::override.
	combining_handle_adapter (combining_handle_adapter &&o) noexcept
	Implicit move construction of combining_handle_adapter permitted.
	combining_handle_adapter (const combining_handle_adapter &)=delete
	No copy construction (use clone())
combining_handle_adapter &	operator= (combining_handle_adapter &&o) noexcept
	Move assignment of combining_handle_adapter permitted.
combining_handle_adapter &	operator= (const combining_handle_adapter &)=delete
	No copy assignment.
void	swap (combining_handle_adapter &o) noexcept
	Swap with another instance.

Detailed Description

template<template< class, class > class Op, class Target, class Source>
class llfio_v2_xxx::algorithm::combining_handle_adapter< Op, Target, Source >

A handle combining the data from one or two other handles.

Template Parameters

Op	Policy class determining what kind of combination ought to be performed.
Target	The type of the target handle.
Source	The type of an optional additional source handle, or void to disable.

Warning

This class is still in development, do not use.

This adapter class is a handle implementation which combines one or two other handle implementations in some way determined by Op which must match the form of:

template<class Target, class Source> struct Op
{
  using buffer_type = typename Target::buffer_type;
  using const_buffer_type = typename Target::const_buffer_type;
 
  // Called by default implementation of read() to perform combines of reads
  static result<buffer_type> do_read(buffer_type out, buffer_type t, buffer_type s) noexcept;
  // Called by default implementation of write() to perform combines of writes
  static result<const_buffer_type> do_write(buffer_type t, buffer_type s, const_buffer_type in) noexcept;
  // Called by default implementation of write() to adjust returned buffers
  static result<const_buffers_type> adjust_written_buffers(const_buffers_type out, const_buffer_type twritten, const_buffer_type toriginal) noexcept;
 
  // Inherited into the resulting combining_handle_adapter
  // Used to inject/override custom member functions and/or eliminate the need for
  // do_read and do_write
  template<class Base> struct override : public Base { using Base::Base; };
};

If both input handle types have a base of file_handle, combining_handle_adapter inherits from file_handle and provides the extra member functions which file_handle provides over byte_io_handle. If not, it inherits from byte_io_handle, and provides that class' reduced functionality instead.

The default implementation of read() and write() allocate temporary buffers, and run Op::do_read() and Op::do_write() on each individual buffer issued by the end user of the combined handles. If each total request is below a page size, the stack is used, else map_handle::map() is used to get whole pages.

Note

If OpenMP is available, LLFIO_DISABLE_OPENMP is not defined, and flag::disable_parallelism is not set, the buffer fill from the two attached handles will be done concurrently.

Combined reads may read less than inputs, but note that offset and buffers fetched from inputs are those of the request. Combined writes may write less than inputs, but again offset used is that of the request. In other words, this adapter is intended for bulk, mostly 1-to-1, combination and transformation of scatter gather buffers. It is not intended for processing scatter gather buffers.

If just one handle type is supplied (the additional source type is void), then instead of combining, this handle adapter is transforming. Op::do_read() and Op::do_write() will be called with the second of the input buffers empty.

The defaults for the virtual functions may not suit your use case, in which case you can override them in the Op::override class.

Destroying the adapter does not destroy the attached handles. Closing the adapter does close the attached handles.

Todo:

I have been lazy and used public inheritance from byte_io_handle and file_handle. I should use protected inheritance to prevent slicing, and expose all the public functions by hand.

---

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

• include/llfio/v2.0/algorithm/handle_adapter/combining.hpp