1
/* $Id: blast_hspfilter.h,v 1.1 2009/05/27 20:31:32 kazimird Exp $
2
* ===========================================================================
5
* National Center for Biotechnology Information
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.
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
22
* Please cite the author in any work or product based on this material.
24
* ===========================================================================
30
/** @file blast_hspfilter.h
31
* Declaration of ADT to filter and/or process HSPs in the BLAST engine.
34
#ifndef ALGO_BLAST_CORE__BLAST_HSPFILTER_H
35
#define ALGO_BLAST_CORE__BLAST_HSPFILTER_H
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 <connect/ncbi_core.h>
46
/**--------------------------------writer-----------------------------*/
47
/** forwarded declarations */
48
typedef struct BlastHSPWriter BlastHSPWriter;
50
/** Function pointer typedef to implement hsp_writer */
51
typedef BlastHSPWriter* (*BlastHSPWriterNewFn) (void*, BlastQueryInfo*);
52
typedef BlastHSPWriter* (*BlastHSPWriterFreeFn) (BlastHSPWriter*);
53
typedef int (*BlastHSPWriterInitFn) (void*, BlastHSPResults*);
54
typedef int (*BlastHSPWriterRunFn) (void*, BlastHSPList*);
55
typedef int (*BlastHSPWriterFinalFn)(void*, BlastHSPResults*);
58
/** ADT definition of BlastHSPWriter */
59
struct BlastHSPWriter {
60
void * data; /**< data structure */
61
BlastHSPWriterInitFn InitFnPtr;
62
BlastHSPWriterRunFn RunFnPtr;
63
BlastHSPWriterFinalFn FinalFnPtr;
64
BlastHSPWriterFreeFn FreeFnPtr;
67
/** A wrap of data structure used to create a writer */
68
typedef struct BlastHSPWriterInfo {
70
BlastHSPWriterNewFn NewFnPtr;
73
/** A generic function to create writer
74
* @param writer_info structure containing information to create the
75
* BlastHSPWriter. This will be free'd in this function and thus will be NULL
76
* on function exit [in|out]
80
BlastHSPWriterNew(BlastHSPWriterInfo** writer_info, BlastQueryInfo *query_info);
82
/**--------------------------------pipe------------------------------*/
83
/** forwarded declarations */
84
typedef struct BlastHSPPipe BlastHSPPipe;
86
/** Function pointer typedef to implement hsp_pipe */
87
typedef BlastHSPPipe* (*BlastHSPPipeNewFn) (void*, BlastQueryInfo*);
88
typedef BlastHSPPipe* (*BlastHSPPipeFreeFn) (BlastHSPPipe*);
89
typedef int (*BlastHSPPipeRunFn) (void*, BlastHSPResults*);
91
/** ADT definition of BlastHSPPipe */
93
void * data; /**< data structure */
94
BlastHSPPipeRunFn RunFnPtr;
95
BlastHSPPipeFreeFn FreeFnPtr;
96
BlastHSPPipe* next; /**< the next pipe in chain*/
99
/** A wrap of data structure used to create a pipe */
100
typedef struct BlastHSPPipeInfo {
102
BlastHSPPipeNewFn NewFnPtr;
103
struct BlastHSPPipeInfo* next; /**< the next pipe inf in chain*/
106
/** Adds node to the linked list starting a head, which should be NULL when
107
* initializing the linked list, on subsequent calls, new nodes will be
108
* appended to the list.
109
* @param head head of the linked list [in|out]
110
* @param node the node to add, ownership is assumed by the linked list [in]
111
* @return node most recently added
112
* @note there is no explicit free function for a linked list of
113
* BlastHSPPipeInfo structures because this is free'd in BlastHSPPipeNew
116
BlastHSPPipeInfo* BlastHSPPipeInfo_Add(BlastHSPPipeInfo** head,
117
BlastHSPPipeInfo* node);
119
/** A generic function to create pipe.
120
* @param pipe_info linked list of pipe info structures which specifies how to
121
* construct the BlastHSPPipe objects. This object's ownership is assumed by
122
* the BlastHSPPipe, and thus this field is NULL on function exit [in]
123
* @param query_info argument used in construction for all BlastHSPPipe objects
128
BlastHSPPipeNew(BlastHSPPipeInfo **pipe_info, BlastQueryInfo *query_info);
132
/**--------------------------------docs------------------------------*/
134
* @page _impl_blast_hspfilter_howto Implementing the BlastHSPFilter interface
136
* BlastHSPFilter interface includes BlastHSPWriter and BlastHSPPipe.
137
* The former is used only in preliminary stage to process BlastHSPList coming
138
* directly from scans, whereas the latter can be used in both preliminary and
139
* traceback stages to process the already-collected BlastHSPResults.
141
* Implementations of both types are similar.
142
* As an example, to implement MyWriter, the following must be declared in
143
* hspfilter_mywriter.h and implemented in hspfilter_mywriter.c:
146
* // Introduce data structure to describe MyWriter filtering parameters
147
* typedef struct BlastHSPMyWriterParams {...} BlastHSPMyWriterParams;
148
* // Function to create MyWriter filtering parameters.
149
* BlastHSPMyWriterParams*
150
* BlastHSPMyWriterParamsNew(...);
151
* // Function to create the BlastWriterInfo structure associated with MyWriter.
152
* BlastHSPWriterInfo*
153
* BlastHSPMyWriterInfoNew(BlastHSPMyWriterParams*);
157
* In addition, the following should be implemented in hspfilter_mywriter.c:
160
* // Any auxillary data structures MyWriter may use to store between-call data.
161
* typedef struct MyWriterData {...} MyWriterData;
162
* // The following are functions to implement BlastHSPWriter interface.
163
* // Function to initiate MyWriterData from BlastHSPResults
164
* static int s_MyWriterInit(void*, BlastHSPResults*);
165
* // Function to finalize MyWriterData to BlastHSPResults
166
* static int s_MyWriterFinal(void*, BlastHSPResults*);
167
* // Function to process BlastHSPList and save results to MyWriterData
168
* // Must call Blast_HSPListFree() before returning
169
* static int s_MyWriterRun(void*, BlastHSPList*);
170
* // Function to free MyWriter.
171
* // Must free mywriter parameters before returning
172
* static BlastHSPWriter* s_MyWriterFree(BlastHSPWriter*);
173
* // Function to create MyWriter.
174
* static BlastHSPWriter* s_MyWriterNew(void*, BlastQueryInfo*);
184
#endif /* ALGO_BLAST_CORE__BLAST_HSPFILTER_H */
added
removed
algo/blast/core/blast_hspfilter.h
