[Search] Use a buffer to cache the intermediate results between search incovations such that memory allocations are reduced on multiple invocations of search.

[rrahn]

Description

A thread local buffer used for the search can have a impact on the performance by avoiding unncessary memory allocations which also have to be synchronised by the OS.

Also see here for possible improvements: seqan/seqan3#1528

Acceptance Criteria

• the buffer is automatically always available. Nothing changes from the user perspective.
• no realllocations happen between search invocations
• the buffer is cleared before the search is invoked but not shrinked.

Tasks

• how can this be designed and implemented?

Definition of Done

• Implementation and design approved
• Unit tests pass
• Test coverage = 100%
• Microbenchmarks added and/or affected microbenchmarks < 5% performance drop
• API documentation added
• Tutorial/teaching material added
• Test suite compiles in less than 30 seconds (on travis)
• Changelog entry added

[h-2]

how can this be designed and implemented?

• low-level utilities like .locate() on the iterators need an out-parameter version.
• add a publicly documented struct called search_buffers whose members are public, but not part of the API and not visible to user doc.
• one member should be a buffer for the occurrences that is passed to .locate() by in-out parameter (.locate() appends to this buffer).
• actual member it is not one buffer, but a vector of buffers (one for every thread)
• regular search creates one object of type search_buffer and passes the respective member to down-stream functions.
• a config object is added that allows the user to create an object outside the function call. In this case the search doesn't create an object but uses the one provided by the config element.

So for regular usage nothing changes, but users can optionally pass in an external buffers object via the config system. The internals of this type are not exposed and can therefore be changed at any time.

[rrahn]

Resolution 10.06.2020

1. We will investigate a strategy using pmr::vector and polymorphic resource to make it easy to provide a generic buffer from outside without knowing the type.

2. Agent-Client pattern like for client pattern?

[h-2]

Hm, that sounds quite complicated (for the user), but I don't know what you have discussed yet. Why do we need polymorphism? We know the type of the buffers.

My proposal would look like this:

seqan3::search_buffers buffers; // the user doesn't know what's inside, but we do

seqan3::configuration const default_cfg = seqan3::search_cfg::max_error_total{zero_errors} |
                                              seqan3::search_cfg::max_error_substitution{zero_errors} |
                                              seqan3::search_cfg::max_error_insertion{zero_errors} |
                                              seqan3::search_cfg::max_error_deletion{zero_errors} |
                                              seqan3::search_cfg::output_query_id |
                                              seqan3::search_cfg::output_reference_id |
                                              seqan3::search_cfg::output_reference_begin_position |
                                              seqan3::search_cfg::hit_all |
                                              seqan3::search_cfg::with_buffers{buffers}; // <--------

// after that, search normally with the config