NCBI C++ ToolKit
Classes | Typedefs | Functions | Variables
blast_hspstream.h File Reference

Declaration of ADT to save and retrieve lists of HSPs in the BLAST engine. More...

#include <algo/blast/core/ncbi_std.h>
#include <algo/blast/core/blast_export.h>
#include <algo/blast/core/blast_hits.h>
#include <algo/blast/core/split_query.h>
#include <algo/blast/core/blast_program.h>
#include <algo/blast/core/blast_hspfilter.h>
#include <algo/blast/core/spliced_hits.h>
#include <connect/ncbi_core.h>
+ Include dependency graph for blast_hspstream.h:
+ This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Go to the SVN repository for this file.

Classes

struct  SSortByScoreStruct
 Auxiliary structure to allow sorting the results by score for the composition-based statistics code. More...
 
struct  BlastHSPStreamResultBatch
 structure used to hold a collection of hits retrieved from the HSPStream More...
 
struct  BlastHSPStream
 Default implementation of BlastHSPStream. More...
 

Typedefs

typedef struct SSortByScoreStruct SSortByScoreStruct
 Auxiliary structure to allow sorting the results by score for the composition-based statistics code. More...
 
typedef struct BlastHSPStreamResultBatch BlastHSPStreamResultBatch
 structure used to hold a collection of hits retrieved from the HSPStream More...
 
typedef struct BlastHSPStream BlastHSPStream
 Default implementation of BlastHSPStream. More...
 

Functions

BlastHSPStreamResultBatchBlast_HSPStreamResultBatchInit (Int4 num_hsplists)
 create a new batch to hold HSP results More...
 
BlastHSPStreamResultBatchBlast_HSPStreamResultBatchFree (BlastHSPStreamResultBatch *batch)
 free a batch of HSP results. More...
 
BlastHSPStreamResultBatchBlast_HSPStreamResultBatchReset (BlastHSPStreamResultBatch *batch)
 free the list of HSPLists within a batch More...
 
BlastHSPStreamBlastHSPStreamNew (EBlastProgramType program, const BlastExtensionOptions *extn_opts, Boolean sort_on_read, Int4 num_queries, BlastHSPWriter *writer)
 Initialize the HSP stream. More...
 
BlastHSPStreamBlastHSPStreamFree (BlastHSPStream *hsp_stream)
 Frees the BlastHSPStream structure by invoking the destructor function set by the user-defined constructor function when the structure is initialized (indirectly, by BlastHSPStreamNew). More...
 
void BlastHSPStreamClose (BlastHSPStream *hsp_stream)
 Closes the BlastHSPStream structure for writing. More...
 
void BlastHSPStreamSimpleClose (BlastHSPStream *hsp_stream)
 Closes the BlastHSPStream structure for writing without any sorting as done in BlastHSPStreamClose. More...
 
void BlastHSPStreamMappingClose (BlastHSPStream *hsp_stream, BlastMappingResults *results)
 Closes BlastHSPStream structure for mapping and produces BlastMappingResults. More...
 
void BlastHSPStreamTBackClose (BlastHSPStream *hsp_stream, BlastHSPResults *results)
 Closes the BlastHSPStream structure after traceback. More...
 
int BlastHSPStreamMerge (SSplitQueryBlk *squery_blk, Uint4 chunk_num, BlastHSPStream *hsp_stream, BlastHSPStream *combined_hsp_stream)
 Moves the HSPlists from an HSPStream into the list contained by a second HSPStream. More...
 
int BlastHSPStreamWrite (BlastHSPStream *hsp_stream, BlastHSPList **hsp_list)
 Invokes the user-specified write function for this BlastHSPStream implementation. More...
 
int BlastHSPStreamRead (BlastHSPStream *hsp_stream, BlastHSPList **hsp_list)
 Invokes the user-specified read function for this BlastHSPStream implementation. More...
 
int BlastHSPStreamBatchRead (BlastHSPStream *hsp_stream, BlastHSPStreamResultBatch *batch)
 Batch read function for this BlastHSPStream implementation. More...
 
int BlastHSPStreamRegisterMTLock (BlastHSPStream *hsp_stream, MT_LOCK lock)
 Attach a mutex lock to a stream to protect multiple access during writing. More...
 
int BlastHSPStreamRegisterPipe (BlastHSPStream *hsp_stream, BlastHSPPipe *pipe, EBlastStage stage)
 Insert the user-specified pipe to the *end* of the pipeline. More...
 
void BlastHSPCBSStreamClose (BlastHSPStream *hsp_stream, int hitlist_size)
 

Variables

const int kBlastHSPStream_Error
 Standard error return value for BlastHSPStream methods. More...
 
const int kBlastHSPStream_Success
 Standard success return value for BlastHSPStream methods. More...
 
const int kBlastHSPStream_Eof
 Return value when the end of the stream is reached (applicable to read method only) More...
 

Detailed Description

Declaration of ADT to save and retrieve lists of HSPs in the BLAST engine.

Definition in file blast_hspstream.h.

Typedef Documentation

◆ BlastHSPStream

Default implementation of BlastHSPStream.

◆ BlastHSPStreamResultBatch

structure used to hold a collection of hits retrieved from the HSPStream

◆ SSortByScoreStruct

Auxiliary structure to allow sorting the results by score for the composition-based statistics code.

Function Documentation

◆ Blast_HSPStreamResultBatchFree()

BlastHSPStreamResultBatch* Blast_HSPStreamResultBatchFree ( BlastHSPStreamResultBatch batch)

free a batch of HSP results.

Note that the HSPLists themselves are not freed

Parameters
batchStructure to free
Returns
Always NULL

Definition at line 628 of file blast_hspstream.c.

References BlastHSPStreamResultBatch::hsplist_array, NULL, and sfree.

Referenced by BlastHSPStreamToHSPStreamResultsBatch(), and s_BlastHSPStreamResultsBatchArrayReset().

◆ Blast_HSPStreamResultBatchInit()

BlastHSPStreamResultBatch* Blast_HSPStreamResultBatchInit ( Int4  num_hsplists)

create a new batch to hold HSP results

Parameters
num_hsplistsMaximum number of results to hold
Returns
Pointer to newly allocated structure

Definition at line 617 of file blast_hspstream.c.

References calloc(), and BlastHSPStreamResultBatch::hsplist_array.

Referenced by BlastHSPStreamToHSPStreamResultsBatch().

◆ Blast_HSPStreamResultBatchReset()

BlastHSPStreamResultBatch* Blast_HSPStreamResultBatchReset ( BlastHSPStreamResultBatch batch)

free the list of HSPLists within a batch

Parameters
batchStructure to reset
Returns
the input batch

Definition at line 639 of file blast_hspstream.c.

References Blast_HSPListFree(), BlastHSPStreamResultBatch::hsplist_array, i, NULL, and BlastHSPStreamResultBatch::num_hsplists.

Referenced by BLAST_ComputeTraceback_MT(), and s_BlastHSPStreamResultsBatchArrayReset().

◆ BlastHSPCBSStreamClose()

void BlastHSPCBSStreamClose ( BlastHSPStream hsp_stream,
int  hitlist_size 
)

◆ BlastHSPStreamBatchRead()

int BlastHSPStreamBatchRead ( BlastHSPStream hsp_stream,
BlastHSPStreamResultBatch batch 
)

Batch read function for this BlastHSPStream implementation.

Parameters
hsp_streamThe BlastHSPStream object [in]
batchList of HSP lists for the HSPStream to return. The caller acquires ownership of all HSP lists returned [out]
Returns
kBlastHSPStream_Success on success, kBlastHSPStream_Error, or kBlastHSPStream_Eof on end of stream

Definition at line 568 of file blast_hspstream.c.

References BlastHSPStreamClose(), BlastHSPStreamResultBatch::hsplist_array, i, kBlastHSPStream_Eof, kBlastHSPStream_Error, kBlastHSPStream_Success, BlastHSPStreamResultBatch::num_hsplists, BlastHSPStream::num_hsplists, BlastHSPList::oid, BlastHSPStream::results, BlastHSPStream::results_sorted, and BlastHSPStream::sorted_hsplists.

Referenced by BlastHSPStreamToHSPStreamResultsBatch().

◆ BlastHSPStreamClose()

void BlastHSPStreamClose ( BlastHSPStream hsp_stream)

◆ BlastHSPStreamFree()

BlastHSPStream* BlastHSPStreamFree ( BlastHSPStream hsp_stream)

Frees the BlastHSPStream structure by invoking the destructor function set by the user-defined constructor function when the structure is initialized (indirectly, by BlastHSPStreamNew).

If the destructor function pointer is not set, a memory leak could occur.

Parameters
hsp_streamBlastHSPStream to free [in]
Returns
NULL

Frees the BlastHSPStream structure by invoking the destructor function set by the user-defined constructor function when the structure is initialized (indirectly, by BlastHSPStreamNew).

Free the BlastHSPStream with its HSP list collector data structure.

Parameters
hsp_streamThe HSP stream to free [in]
Returns
NULL.

Definition at line 46 of file blast_hspstream.c.

References Blast_HSPListFree(), Blast_HSPResultsFree(), BlastHSPWriter::FreeFnPtr, MT_LOCK_Delete(), BlastHSPPipe::next, NULL, BlastHSPStream::num_hsplists, BlastHSPStream::pre_pipe, BlastHSPStream::results, sfree, BlastHSPStream::sort_by_score, BlastHSPStream::sorted_hsplists, BlastHSPStream::tback_pipe, BlastHSPStream::writer, and BlastHSPStream::x_lock.

Referenced by BlastSetupPreliminarySearchEx(), BOOST_AUTO_TEST_CASE(), Deleter< BlastHSPStream >::Delete(), CRedoAlignmentTestFixture::runRedoAlignmentCoreUnitTest(), testHSPStream(), CTracebackSearchTestFixture::x_GetSampleHspStream(), and CTracebackSearchTestFixture::x_GetSelfHitHspStream().

◆ BlastHSPStreamMappingClose()

void BlastHSPStreamMappingClose ( BlastHSPStream hsp_stream,
BlastMappingResults results 
)

Closes BlastHSPStream structure for mapping and produces BlastMappingResults.

Parameters
hsp_streamThe stream to close [in] [out]
resultsThe results [in] [out]

Definition at line 209 of file blast_hspstream.c.

References BlastHSPWriter::data, BlastHSPWriter::FinalFnPtr, BlastHSPWriter::InitFnPtr, MT_LOCK_Delete(), BlastHSPStream::results, TRUE, BlastHSPStream::writer, BlastHSPStream::writer_finalized, BlastHSPStream::writer_initialized, and BlastHSPStream::x_lock.

Referenced by CMagicBlast::Run(), and CMagicBlast::RunEx().

◆ BlastHSPStreamMerge()

int BlastHSPStreamMerge ( SSplitQueryBlk squery_blk,
Uint4  chunk_num,
BlastHSPStream stream1,
BlastHSPStream stream2 
)

Moves the HSPlists from an HSPStream into the list contained by a second HSPStream.

Parameters
squery_blkInformation needed to map HSPs from one HSPstream to the combined HSPstream [in]
chunk_numUsed to choose a subset of the information in squery_blk [in]
hsp_streamThe stream to merge [in][out]
combined_hsp_streamThe stream that will contain the HSPLists of the first stream [in][out]

Moves the HSPlists from an HSPStream into the list contained by a second HSPStream.

The HSPs from the first stream are moved to the second stream.

Parameters
squery_blkStructure controlling the merge process [in]
chunk_numUnique integer assigned to hsp_stream [in]
stream1The stream to merge [in][out]
stream2The stream that will contain the HSPLists of the first stream [in][out]

Definition at line 399 of file blast_hspstream.c.

References ASSERT, BLAST_ContextToFrame(), BLAST_GetNumberOfContexts(), Blast_HitListMerge(), Blast_HSPListSortByScore(), BlastHSP::context, BlastSeg::end, FALSE, BlastSeg::frame, BlastSeg::gapped_start, BlastHSPResults::hitlist_array, BlastHSPList::hsp_array, BlastHSPList::hspcnt, BlastHitList::hsplist_array, BlastHitList::hsplist_count, i, INT4_MIN, kBlastHSPStream_Error, kBlastHSPStream_Success, MAX, NULL, NUM_FRAMES, BlastHSPResults::num_queries, BlastSeg::offset, BlastHSPList::oid, BlastHSPStream::program, BlastHSP::query, BlastHSPList::query_index, BlastHSPStream::results, BlastHSPStream::results_sorted, s_FinalizeWriter(), BlastHSP::score, sfree, SplitQueryBlk_AllowGap(), SplitQueryBlk_GetChunkOverlapSize(), SplitQueryBlk_GetContextOffsetsForChunk(), SplitQueryBlk_GetQueryContextsForChunk(), SplitQueryBlk_GetQueryIndicesForChunk(), BlastHSP::subject, and UINT4_MAX.

Referenced by CBlastPrelimSearch::Run().

◆ BlastHSPStreamNew()

BlastHSPStream* BlastHSPStreamNew ( EBlastProgramType  program,
const BlastExtensionOptions extn_opts,
Boolean  sort_on_read,
Int4  num_queries,
BlastHSPWriter writer 
)

◆ BlastHSPStreamRead()

int BlastHSPStreamRead ( BlastHSPStream hsp_stream,
BlastHSPList **  hsp_list_out 
)

Invokes the user-specified read function for this BlastHSPStream implementation.

Parameters
hsp_streamThe BlastHSPStream object [in]
hsp_listList of HSPs for the HSPStream to return. The caller acquires ownership of the hsp_list [out]
Returns
kBlastHSPStream_Success on success, kBlastHSPStream_Error, or kBlastHSPStream_Eof on end of stream

Invokes the user-specified read function for this BlastHSPStream implementation.

Once an HSP list is read from the stream, it relinquishes ownership and removes it from the internal results data structure.

Parameters
hsp_streamThe HSP stream to read from [in]
hsp_list_outThe read HSP list. [out]
Returns
Success, error, or end of reading, when nothing left to read.

Definition at line 271 of file blast_hspstream.c.

References BlastHSPStreamClose(), SSortByScoreStruct::first_query_index, BlastHSPResults::hitlist_array, BlastHitList::hsplist_array, BlastHitList::hsplist_count, kBlastHSPStream_Eof, kBlastHSPStream_Error, kBlastHSPStream_Success, NULL, BlastHSPStream::num_hsplists, BlastHSPResults::num_queries, BlastHSPList::query_index, BlastHSPStream::results, BlastHSPStream::results_sorted, BlastHSPStream::sort_by_score, and BlastHSPStream::sorted_hsplists.

Referenced by Blast_HSPResultsFromHSPStream(), Blast_RedoAlignmentCore_MT(), BOOST_AUTO_TEST_CASE(), s_RPSComputeTraceback(), and testHSPStream().

◆ BlastHSPStreamRegisterMTLock()

int BlastHSPStreamRegisterMTLock ( BlastHSPStream hsp_stream,
MT_LOCK  lock 
)

Attach a mutex lock to a stream to protect multiple access during writing.

Parameters
hsp_streamThe stream to attach [in]
lockPointer to locking structure for writing by multiple threads. Locking will not be performed if NULL. [in]

Definition at line 697 of file blast_hspstream.c.

References MT_LOCK_Delete(), and BlastHSPStream::x_lock.

Referenced by BlastSetupPreliminarySearchEx(), CBlastPrelimSearch::SetNumberOfThreads(), and testHSPStream().

◆ BlastHSPStreamRegisterPipe()

int BlastHSPStreamRegisterPipe ( BlastHSPStream hsp_stream,
BlastHSPPipe pipe,
EBlastStage  stage 
)

Insert the user-specified pipe to the *end* of the pipeline.

Parameters
hsp_streamThe BlastHSPStream object [in]
pipeThe pipe to be registered [in]
stageAt what stage should this pipeline be applied [in]

Definition at line 709 of file blast_hspstream.c.

References ePrelimSearch, eTracebackSearch, BlastHSPPipe::next, NULL, BlastHSPStream::pre_pipe, and BlastHSPStream::tback_pipe.

Referenced by BlastSetupPreliminarySearchEx().

◆ BlastHSPStreamSimpleClose()

void BlastHSPStreamSimpleClose ( BlastHSPStream hsp_stream)

Closes the BlastHSPStream structure for writing without any sorting as done in BlastHSPStreamClose.

Any subsequent attempt to write to the stream will return error.

Parameters
hsp_streamThe stream to close [in] [out]

Definition at line 226 of file blast_hspstream.c.

References MT_LOCK_Delete(), s_FinalizeWriter(), and BlastHSPStream::x_lock.

◆ BlastHSPStreamTBackClose()

void BlastHSPStreamTBackClose ( BlastHSPStream hsp_stream,
BlastHSPResults results 
)

Closes the BlastHSPStream structure after traceback.

This is mainly to provide a chance to apply post-traceback pipes.

Parameters
hsp_streamThe stream to close [in] [out]
resultsThe traceback results [in] [out]

Closes the BlastHSPStream structure after traceback.

This is mainly to provide a chance to apply post-traceback pipes.

Parameters
hsp_streamThe HSP stream to close [in] [out]
resultsThe traceback results [in] [out]

Definition at line 241 of file blast_hspstream.c.

References BlastHSPPipe::data, BlastHSPPipe::FreeFnPtr, BlastHSPPipe::next, BlastHSPPipe::RunFnPtr, and BlastHSPStream::tback_pipe.

Referenced by BLAST_ComputeTraceback_MT(), Blast_RedoAlignmentCore_MT(), and s_RPSComputeTraceback().

◆ BlastHSPStreamWrite()

int BlastHSPStreamWrite ( BlastHSPStream hsp_stream,
BlastHSPList **  hsp_list 
)

Invokes the user-specified write function for this BlastHSPStream implementation.

Parameters
hsp_streamThe BlastHSPStream object [in]
hsp_listList of HSPs for the HSPStream to keep track of. The caller releases ownership of the hsp_list [in]
Returns
kBlastHSPStream_Success on success, otherwise kBlastHSPStream_Error

Invokes the user-specified write function for this BlastHSPStream implementation.

The HSP stream assumes ownership of the HSP list and sets the dereferenced pointer to NULL.

Parameters
hsp_streamStream to write to. [in] [out]
hsp_listPointer to the HSP list to save in the collector. [in]
Returns
Success or error, if stream is already closed for writing.

Definition at line 339 of file blast_hspstream.c.

References BlastHSPWriter::data, eMT_Lock, eMT_Unlock, FALSE, BlastHSPWriter::InitFnPtr, kBlastHSPStream_Error, kBlastHSPStream_Success, MT_LOCK_Do, NULL, BlastHSPStream::results, BlastHSPStream::results_sorted, BlastHSPWriter::RunFnPtr, TRUE, BlastHSPStream::writer, BlastHSPStream::writer_initialized, and BlastHSPStream::x_lock.

Referenced by BLAST_PreliminarySearchEngine(), BOOST_AUTO_TEST_CASE(), DoAnchoredSearch(), CHspStreamWriteThread::Main(), CRedoAlignmentTestFixture::runRedoAlignmentCoreUnitTest(), s_RPSPreliminarySearchEngine(), testHSPStream(), CTracebackSearchTestFixture::x_GetSampleHspStream(), and CTracebackSearchTestFixture::x_GetSelfHitHspStream().

Variable Documentation

◆ kBlastHSPStream_Eof

const int kBlastHSPStream_Eof
extern

Return value when the end of the stream is reached (applicable to read method only)

Definition at line 262 of file blast_hspstream.c.

Referenced by Blast_HSPResultsFromHSPStream(), Blast_RedoAlignmentCore_MT(), BlastHSPStreamBatchRead(), BlastHSPStreamRead(), BlastHSPStreamToHSPStreamResultsBatch(), BOOST_AUTO_TEST_CASE(), s_RPSComputeTraceback(), and testHSPStream().

◆ kBlastHSPStream_Error

const int kBlastHSPStream_Error
extern

Standard error return value for BlastHSPStream methods.

Definition at line 260 of file blast_hspstream.c.

Referenced by BlastHSPStreamBatchRead(), BlastHSPStreamMerge(), BlastHSPStreamRead(), BlastHSPStreamWrite(), and testHSPStream().

◆ kBlastHSPStream_Success

const int kBlastHSPStream_Success
extern
Modified on Sat Mar 02 10:53:41 2024 by modify_doxy.py rev. 669887