61
76
* @param batch Structure to free
62
77
* @return Always NULL
64
80
BlastHSPStreamResultBatch * Blast_HSPStreamResultBatchFree(
65
81
BlastHSPStreamResultBatch *batch);
67
83
/** free the list of HSPLists within a batch
68
84
* @param batch Structure to reset
70
87
void Blast_HSPStreamResultBatchReset(BlastHSPStreamResultBatch *batch);
72
/** The BlastHSPStream ADT is an opaque data type that defines a thread-safe
73
* interface which is used by the core BLAST code to save lists of HSPs.
74
* The interface currently provides the following services:
75
* - Management of the ADT (construction, destruction)
76
* - Writing lists of HSPs to the ADT
77
* - Reading lists of HSPs from the ADT
78
* - Merging two instances of the ADT
80
* The default implementation simply buffers HSPs from one stage of the
81
* algorithm to the next @sa FIXME
82
* Implementations of this interface should provide functions for all
83
* the functions listed above.
85
typedef struct BlastHSPStream BlastHSPStream;
87
/** Function pointer typedef to create a new BlastHSPStream structure.
88
* First argument is a pointer to the structure to be populated (allocated for
89
* client implementations), second argument should be typecast'd to the
90
* correct type by user-defined constructor function */
91
typedef BlastHSPStream* (*BlastHSPStreamConstructor) (BlastHSPStream*, void*);
93
/** Function pointer typedef to deallocate a BlastHSPStream structure.
94
* Argument is the BlastHSPStream structure to free, always returns NULL. */
95
typedef BlastHSPStream* (*BlastHSPStreamDestructor) (BlastHSPStream*);
97
/** Function pointer typedef to implement the read/write functionality of the
98
* BlastHSPStream. The first argument is the BlastHSPStream structure used,
99
* second argument is the list of HSPs to be saved/read (reading assumes
100
* ownership, writing releases ownership) */
101
typedef int (*BlastHSPStreamMethod) (BlastHSPStream*, BlastHSPList**);
103
/** Function pointer typedef to implement the batch read functionality of the
104
* BlastHSPStream. The first argument is the BlastHSPStream structure used,
105
* second argument is the list of HSP listss that are read (reading assumes
107
typedef int (*BlastHSPStreamBatchReadMethod) (BlastHSPStream*,
108
BlastHSPStreamResultBatch*);
110
/** Function pointer typedef to implement the merge functionality of the
111
* BlastHSPStream. The first argument is the BlastHSPStream structure to merge,
112
* second argument is the BlastHSPStream that will contain the combined
113
* result. Note that this function does not lock either of it inputs */
114
typedef int (*BlastHSPStreamMergeFnType) (SSplitQueryBlk*, Uint4,
115
BlastHSPStream*, BlastHSPStream*);
117
/** Function pointer typedef to implement the close functionality of the
118
* BlastHSPStream. Argument is a pointer to the structure to close for
121
typedef void (*BlastHSPStreamCloseFnType) (BlastHSPStream*);
89
/** Default implementation of BlastHSPStream */
90
typedef struct BlastHSPStream {
91
EBlastProgramType program; /**< BLAST program type */
92
Int4 num_hsplists; /**< number of HSPlists saved */
93
Int4 num_hsplists_alloc; /**< number of entries in sorted_hsplists */
94
BlastHSPList **sorted_hsplists; /**< list of all HSPlists from 'results'
95
combined, sorted in order of
96
decreasing subject OID */
97
BlastHSPResults* results;/**< Structure for saving HSP lists */
98
Boolean results_sorted; /**< Have the results already been sorted?
99
Set to true after the first read call. */
100
/**< Non-NULL if the results should be sorted by score as opposed to subject
101
* OID. This is necessary to meet a pre-condition of the composition-based
102
* statistics processing */
103
SSortByScoreStruct* sort_by_score;
104
MT_LOCK x_lock; /**< Mutex for writing and reading results. */
105
/* support for writer and pipes */
106
BlastHSPWriter* writer; /**< writer to be applied when writing*/
107
Boolean writer_initialized; /**< Is writer already initialized? */
108
BlastHSPPipe *pre_pipe; /**< registered preliminary pipeline (unused
110
BlastHSPPipe *tback_pipe; /**< registered traceback pipeline */
123
113
/*****************************************************************************/
125
/** Structure that contains the information needed for BlastHSPStreamNew to
126
* fully populate the BlastHSPStream structure it returns */
127
typedef struct BlastHSPStreamNewInfo {
128
BlastHSPStreamConstructor constructor; /**< User-defined function to
129
initialize a BlastHSPStream
131
void* ctor_argument; /**< Argument to the above function */
132
} BlastHSPStreamNewInfo;
134
/** Allocates memory for a BlastHSPStream structure and then invokes the
135
* constructor function defined in its first argument, passing the
136
* ctor_argument member of that same structure. If the constructor function
137
* pointer is not set, NULL is returned.
138
* @param bhsn_info Structure defining constructor and its argument to be
139
* invoked from this function [in]
114
/** Initialize the HSP stream.
115
* @param program Type of BlAST program [in]
116
* @param extn_opts Extension options to determine composition-based statistics
118
* @param sort_on_read Should results be sorted on the first read call? Only
119
* applicable if composition-based statistics is on [in]
120
* @param num_queries Number of query sequences in this BLAST search [in]
121
* @param writer Writer to be registered [in]
141
123
NCBI_XBLAST_EXPORT
142
BlastHSPStream* BlastHSPStreamNew(const BlastHSPStreamNewInfo* bhsn_info);
124
BlastHSPStream* BlastHSPStreamNew(EBlastProgramType program,
125
const BlastExtensionOptions* extn_opts,
126
Boolean sort_on_read,
128
BlastHSPWriter* writer);
144
/** Frees the BlastHSPStream structure by invoking the destructor function set
130
/** Frees the BlastHSPStream structure by invoking the destructor function set
145
131
* by the user-defined constructor function when the structure is initialized
146
132
* (indirectly, by BlastHSPStreamNew). If the destructor function pointer is not
147
133
* set, a memory leak could occur.
215
212
* kBlastHSPStream_Eof on end of stream
217
214
NCBI_XBLAST_EXPORT
218
int BlastHSPStreamBatchRead(BlastHSPStream* hsp_stream,
215
int BlastHSPStreamBatchRead(BlastHSPStream* hsp_stream,
219
216
BlastHSPStreamResultBatch* batch);
221
/*****************************************************************************/
222
/* The following enumeration and function are only of interest to implementors
223
* of this interface */
225
/** Defines the methods supported by the BlastHSPStream ADT */
226
typedef enum EMethodName {
227
eConstructor, /**< Constructor for a BlastHSPStream implementation */
228
eDestructor, /**< Destructor for a BlastHSPStream implementation */
229
eRead, /**< Read from the BlastHSPStream */
230
eBatchRead, /**< Batch read from the BlastHSPStream */
231
eWrite, /**< Write to the BlastHSPStream */
232
eMerge, /**< Merge with a second BlastHSPStream */
233
eClose, /**< Close the BlastHSPStream for writing */
234
eMethodBoundary /**< Limit to facilitate error checking */
237
/** Union to encapsulate the supported methods on the BlastHSPStream interface
239
typedef union BlastHSPStreamFunctionPointerTypes {
240
/** Used for read/write function pointers */
241
BlastHSPStreamMethod method;
243
/** Used for constructor function pointer */
244
BlastHSPStreamConstructor ctor;
246
/** Used for destructor function pointer */
247
BlastHSPStreamDestructor dtor;
249
/** Use for merge function pointer */
250
BlastHSPStreamMergeFnType mergeFn;
252
/** Use for merge function pointer */
253
BlastHSPStreamBatchReadMethod batch_read;
255
/** Use for close function pointer */
256
BlastHSPStreamCloseFnType closeFn;
257
} BlastHSPStreamFunctionPointerTypes;
259
/** Sets implementation specific data structure
260
* @param hsp_stream structure to initialize [in]
261
* @param data structure to assign to the hsp_stream [in]
262
* @return kBlastHSPStream_Error if hsp_stream is NULL else,
263
* kBlastHSPStream_Success;
266
int SetData(BlastHSPStream* hsp_stream, void* data);
268
/** Gets implementation specific data structure
269
* @param hsp_stream structure from which to obtain the internal data. It is
270
* expected that the caller (implementation of BlastHSPStream) knows what type
271
* to cast the return value to. [in]
272
* @return pointer to internal data structure of the implementation of the
273
* BlastHSPStream, or NULL if hsp_stream is NULL
276
void* GetData(BlastHSPStream* hsp_stream);
278
/** Use this function to set the pointers to functions implementing the various
279
* methods supported in the BlastHSPStream interface
280
* @param hsp_stream structure to initialize [in]
281
* @param name method for which a function pointer is being provided [in]
282
* @param fnptr_type union containing the pointer to the function specified by
284
* @return kBlastHSPStream_Error if hsp_stream is NULL else,
285
* kBlastHSPStream_Success;
288
int SetMethod(BlastHSPStream* hsp_stream,
290
BlastHSPStreamFunctionPointerTypes fnptr_type);
218
/** Attach a mutex lock to a stream to protect multiple access during writing
219
* @param hsp_stream The stream to attach [in]
220
* @param lock Pointer to locking structure for writing by multiple
221
* threads. Locking will not be performed if NULL. [in]
224
int BlastHSPStreamRegisterMTLock(BlastHSPStream* hsp_stream,
227
/** Insert the user-specified pipe to the *end* of the pipeline.
228
* @param hsp_stream The BlastHSPStream object [in]
229
* @param pipe The pipe to be registered [in]
230
* @param stage At what stage should this pipeline be applied [in]
233
int BlastHSPStreamRegisterPipe(BlastHSPStream* hsp_stream,
292
237
#ifdef __cplusplus
added
removed
algo/blast/core/blast_hspstream.h
