NCBI C Toolkit Cross Reference

C/algo/blast/core/blast_hspstream.h


  1 /*  $Id: blast_hspstream.h,v 1.14 2017/04/05 13:49:16 fukanchi Exp $
  2  * ===========================================================================
  3  *
  4  *                            PUBLIC DOMAIN NOTICE
  5  *               National Center for Biotechnology Information
  6  *
  7  *  This software/database is a "United States Government Work" under the
  8  *  terms of the United States Copyright Act.  It was written as part of
  9  *  the author's official duties as a United States Government employee and
 10  *  thus cannot be copyrighted.  This software/database is freely available
 11  *  to the public for use. The National Library of Medicine and the U.S.
 12  *  Government have not placed any restriction on its use or reproduction.
 13  *
 14  *  Although all reasonable efforts have been taken to ensure the accuracy
 15  *  and reliability of the software and data, the NLM and the U.S.
 16  *  Government do not and cannot warrant the performance or results that
 17  *  may be obtained by using this software or data. The NLM and the U.S.
 18  *  Government disclaim all warranties, express or implied, including
 19  *  warranties of performance, merchantability or fitness for any particular
 20  *  purpose.
 21  *
 22  *  Please cite the author in any work or product based on this material.
 23  *
 24  * ===========================================================================
 25  *
 26  * Author:  Christiam Camacho
 27  *
 28  */
 29 
 30 /** @file blast_hspstream.h
 31  * Declaration of ADT to save and retrieve lists of HSPs in the BLAST engine.
 32  */
 33 
 34 #ifndef ALGO_BLAST_CORE__BLAST_HSPSTREAM_H
 35 #define ALGO_BLAST_CORE__BLAST_HSPSTREAM_H
 36 
 37 #include <algo/blast/core/ncbi_std.h>
 38 #include <algo/blast/core/blast_export.h>
 39 #include <algo/blast/core/blast_hits.h>
 40 #include <algo/blast/core/split_query.h>
 41 #include <algo/blast/core/blast_program.h>
 42 #include <algo/blast/core/blast_hits.h>
 43 #include <algo/blast/core/blast_hspfilter.h>
 44 #include <algo/blast/core/spliced_hits.h>
 45 #include <connect/ncbi_core.h>
 46 
 47 #ifdef __cplusplus
 48 extern "C" {
 49 #endif
 50 
 51 /** Auxiliary structure to allow sorting the results by score for the
 52  * composition-based statistics code */
 53 typedef struct SSortByScoreStruct {
 54     Boolean sort_on_read;    /**< Should the results be sorted on the first read
 55                                call? */
 56     Int4 first_query_index;  /**< Index of the first query to try getting
 57                                results from */
 58 } SSortByScoreStruct;
 59 
 60 /** structure used to hold a collection of hits
 61     retrieved from the HSPStream */
 62 typedef struct BlastHSPStreamResultBatch {
 63     Int4 num_hsplists;          /**< number of lists of HSPs returned */
 64     BlastHSPList **hsplist_array;  /**< array of HSP lists returned */
 65 } BlastHSPStreamResultBatch;
 66 
 67 /** create a new batch to hold HSP results
 68  * @param num_hsplists Maximum number of results to hold
 69  * @return Pointer to newly allocated structure
 70  */
 71 NCBI_XBLAST_EXPORT
 72 BlastHSPStreamResultBatch * Blast_HSPStreamResultBatchInit(
 73                                             Int4 num_hsplists);
 74 
 75 /** free a batch of HSP results. Note that the HSPLists
 76  * themselves are not freed
 77  * @param batch Structure to free
 78  * @return Always NULL
 79  */
 80 NCBI_XBLAST_EXPORT
 81 BlastHSPStreamResultBatch * Blast_HSPStreamResultBatchFree(
 82                                   BlastHSPStreamResultBatch *batch);
 83 
 84 /** free the list of HSPLists within a batch
 85  * @param batch Structure to reset
 86  * @return the input batch
 87  */
 88 NCBI_XBLAST_EXPORT
 89 BlastHSPStreamResultBatch* Blast_HSPStreamResultBatchReset(BlastHSPStreamResultBatch *batch);
 90 
 91 /** Default implementation of BlastHSPStream */
 92 typedef struct BlastHSPStream {
 93    EBlastProgramType program;           /**< BLAST program type */
 94    Int4 num_hsplists;          /**< number of HSPlists saved */
 95    Int4 num_hsplists_alloc;    /**< number of entries in sorted_hsplists */
 96    BlastHSPList **sorted_hsplists; /**< list of all HSPlists from 'results'
 97                                        combined, sorted in order of
 98                                        decreasing subject OID */
 99    BlastHSPResults* results;/**< Structure for saving HSP lists */
100    Boolean results_sorted;  /**< Have the results already been sorted?
101                                Set to true after the first read call. */
102    /**< Non-NULL if the results should be sorted by score as opposed to subject
103     * OID. This is necessary to meet a pre-condition of the composition-based
104     * statistics processing */
105    SSortByScoreStruct* sort_by_score;
106    MT_LOCK x_lock;   /**< Mutex for writing and reading results. */
107    /* support for writer and pipes */
108    BlastHSPWriter* writer;         /**< writer to be applied when writing*/
109    Boolean writer_initialized;     /**< Is writer already initialized? */
110    Boolean writer_finalized;       /**< Is writer ever finalized? */
111    BlastHSPPipe *pre_pipe;         /**< registered preliminary pipeline (unused
112                                     for now) */
113    BlastHSPPipe *tback_pipe;       /**< registered traceback pipeline */
114 } BlastHSPStream;
115 
116 /*****************************************************************************/
117 /** Initialize the HSP stream. 
118  * @param program Type of BlAST program [in]
119  * @param extn_opts Extension options to determine composition-based statistics
120  * mode [in]
121  * @param sort_on_read Should results be sorted on the first read call? Only
122  * applicable if composition-based statistics is on [in]
123  * @param num_queries Number of query sequences in this BLAST search [in]
124  * @param writer Writer to be registered [in]
125  */
126 NCBI_XBLAST_EXPORT
127 BlastHSPStream* BlastHSPStreamNew(EBlastProgramType program,
128                              const BlastExtensionOptions* extn_opts,
129                              Boolean sort_on_read,
130                              Int4 num_queries,
131                              BlastHSPWriter* writer);
132 
133 /** Frees the BlastHSPStream structure by invoking the destructor function set
134  * by the user-defined constructor function when the structure is initialized
135  * (indirectly, by BlastHSPStreamNew). If the destructor function pointer is not
136  * set, a memory leak could occur.
137  * @param hsp_stream BlastHSPStream to free [in]
138  * @return NULL
139  */
140 NCBI_XBLAST_EXPORT
141 BlastHSPStream* BlastHSPStreamFree(BlastHSPStream* hsp_stream);
142 
143 /** Closes the BlastHSPStream structure for writing. Any subsequent attempt
144  * to write to the stream will return error.
145  * @param hsp_stream The stream to close [in] [out]
146  */
147 NCBI_XBLAST_EXPORT
148 void BlastHSPStreamClose(BlastHSPStream* hsp_stream);
149 
150 /** Closes the BlastHSPStream structure for writing without any sorting as done
151  * in BlastHSPStreamClose. Any subsequent attempt to write to the stream will
152  * return error.
153  * @param hsp_stream The stream to close [in] [out]
154  */
155 NCBI_XBLAST_EXPORT
156 void BlastHSPStreamSimpleClose(BlastHSPStream* hsp_stream);
157 
158 /** Closes BlastHSPStream structure for mapping and produces
159  *  BlastMappingResults
160  * @param hsp_stream The stream to close [in] [out]
161  * @param results The results [in] [out]
162 */
163 NCBI_XBLAST_EXPORT
164 void BlastHSPStreamMappingClose(BlastHSPStream* hsp_stream,
165                                 BlastMappingResults* results);
166 
167 /** Closes the BlastHSPStream structure after traceback. 
168  * This is mainly to provide a chance to apply post-traceback pipes.
169  * @param hsp_stream The stream to close [in] [out]
170  * @param results The traceback results [in] [out]
171  */
172 NCBI_XBLAST_EXPORT
173 void BlastHSPStreamTBackClose(BlastHSPStream* hsp_stream,
174                               BlastHSPResults* results);
175 
176 /** Moves the HSPlists from an HSPStream into the list contained
177  * by a second HSPStream
178  * @param squery_blk Information needed to map HSPs from one HSPstream
179  *                   to the combined HSPstream [in]
180  * @param chunk_num Used to choose a subset of the information in
181  *                  squery_blk [in]
182  * @param hsp_stream The stream to merge [in][out]
183  * @param combined_hsp_stream The stream that will contain the
184  *         HSPLists of the first stream [in][out]
185  */
186 NCBI_XBLAST_EXPORT
187 int BlastHSPStreamMerge(SSplitQueryBlk* squery_blk,
188                         Uint4 chunk_num,
189                         BlastHSPStream* hsp_stream,
190                         BlastHSPStream* combined_hsp_stream);
191 
192 /** Standard error return value for BlastHSPStream methods */
193 NCBI_XBLAST_EXPORT
194 extern const int kBlastHSPStream_Error;
195 
196 /** Standard success return value for BlastHSPStream methods */
197 NCBI_XBLAST_EXPORT
198 extern const int kBlastHSPStream_Success;
199 
200 /** Return value when the end of the stream is reached (applicable to read
201  * method only) */
202 NCBI_XBLAST_EXPORT
203 extern const int kBlastHSPStream_Eof;
204 
205 /** Invokes the user-specified write function for this BlastHSPStream
206  * implementation.
207  * @param hsp_stream The BlastHSPStream object [in]
208  * @param hsp_list List of HSPs for the HSPStream to keep track of. The caller
209  * releases ownership of the hsp_list [in]
210  * @return kBlastHSPStream_Success on success, otherwise kBlastHSPStream_Error
211  */
212 NCBI_XBLAST_EXPORT
213 int BlastHSPStreamWrite(BlastHSPStream* hsp_stream, BlastHSPList** hsp_list);
214 
215 /** Invokes the user-specified read function for this BlastHSPStream
216  * implementation.
217  * @param hsp_stream The BlastHSPStream object [in]
218  * @param hsp_list List of HSPs for the HSPStream to return. The caller
219  * acquires ownership of the hsp_list [out]
220  * @return kBlastHSPStream_Success on success, kBlastHSPStream_Error, or
221  * kBlastHSPStream_Eof on end of stream
222  */
223 NCBI_XBLAST_EXPORT
224 int BlastHSPStreamRead(BlastHSPStream* hsp_stream, BlastHSPList** hsp_list);
225 
226 /** Batch read function for this BlastHSPStream implementation.      
227  * @param hsp_stream The BlastHSPStream object [in]
228  * @param batch List of HSP lists for the HSPStream to return. The caller
229  * acquires ownership of all HSP lists returned [out]
230  * @return kBlastHSPStream_Success on success, kBlastHSPStream_Error, or
231  * kBlastHSPStream_Eof on end of stream
232  */
233 NCBI_XBLAST_EXPORT
234 int BlastHSPStreamBatchRead(BlastHSPStream* hsp_stream,
235                             BlastHSPStreamResultBatch* batch);
236 
237 /** Attach a mutex lock to a stream to protect multiple access during writing
238  * @param hsp_stream  The stream to attach [in]
239  * @param lock        Pointer to locking structure for writing by multiple
240  *                    threads. Locking will not be performed if NULL. [in]
241  */
242 NCBI_XBLAST_EXPORT
243 int BlastHSPStreamRegisterMTLock(BlastHSPStream* hsp_stream,
244                                  MT_LOCK lock);
245 
246 /** Insert the user-specified pipe to the *end* of the pipeline.
247  * @param hsp_stream The BlastHSPStream object [in]
248  * @param pipe The pipe to be registered [in]
249  * @param stage At what stage should this pipeline be applied [in]
250  */
251 NCBI_XBLAST_EXPORT
252 int BlastHSPStreamRegisterPipe(BlastHSPStream* hsp_stream,
253                                BlastHSPPipe* pipe,
254                                EBlastStage stage);
255 
256 #ifdef __cplusplus
257 }
258 #endif
259 
260 #endif /* ALGO_BLAST_CORE__BLAST_HSPSTREAM_H */
261 

source navigation ]   [ diff markup ]   [ identifier search ]   [ freetext search ]   [ file search ]  

This page was automatically generated by the LXR engine.
Visit the LXR main site for more information.