blast_hspstream.h
上传用户:yhdzpy8989
上传日期:2007-06-13
资源大小:13604k
文件大小:8k
源码类别:

生物技术

开发平台:

C/C++

  1. /*
  2.  * ===========================================================================
  3.  * PRODUCTION $Log: blast_hspstream.h,v $
  4.  * PRODUCTION Revision 1000.0  2004/06/01 18:11:53  gouriano
  5.  * PRODUCTION PRODUCTION: IMPORTED [GCC34_MSVC7] Dev-tree R1.1
  6.  * PRODUCTION
  7.  * ===========================================================================
  8.  */
  9. #ifndef ALGO_BLAST_CORE__BLAST_HSPSTREAM_H
  10. #define ALGO_BLAST_CORE__BLAST_HSPSTREAM_H
  11. /*  $Id: blast_hspstream.h,v 1000.0 2004/06/01 18:11:53 gouriano Exp $
  12.  * ===========================================================================
  13.  *
  14.  *                            PUBLIC DOMAIN NOTICE
  15.  *               National Center for Biotechnology Information
  16.  *
  17.  *  This software/database is a "United States Government Work" under the
  18.  *  terms of the United States Copyright Act.  It was written as part of
  19.  *  the author's official duties as a United States Government employee and
  20.  *  thus cannot be copyrighted.  This software/database is freely available
  21.  *  to the public for use. The National Library of Medicine and the U.S.
  22.  *  Government have not placed any restriction on its use or reproduction.
  23.  *
  24.  *  Although all reasonable efforts have been taken to ensure the accuracy
  25.  *  and reliability of the software and data, the NLM and the U.S.
  26.  *  Government do not and cannot warrant the performance or results that
  27.  *  may be obtained by using this software or data. The NLM and the U.S.
  28.  *  Government disclaim all warranties, express or implied, including
  29.  *  warranties of performance, merchantability or fitness for any particular
  30.  *  purpose.
  31.  *
  32.  *  Please cite the author in any work or product based on this material.
  33.  *
  34.  * ===========================================================================
  35.  *
  36.  * Author:  Christiam Camacho
  37.  *
  38.  */
  39. /** @file blast_hspstream.h
  40.  * Declaration of ADT to save and retrieve lists of HSPs in the BLAST engine.
  41.  */
  42. #include <algo/blast/core/blast_hits.h>
  43. #ifdef __cplusplus
  44. extern "C" {
  45. #endif
  46. /** The BlastHSPStream ADT is an opaque data type that defines a thread-safe
  47.  *  interface which is used by the core BLAST code to save lists of HSPs.
  48.  *  The interface currently provides the following services:
  49.  *  - Management of the ADT (construction, destruction)
  50.  *  - Writing lists of HSPs to the ADT
  51.  *  - Reading lists of HSPs from the ADT
  52.  *  .
  53.  *  The default implementation simply buffers HSPs from one stage of the
  54.  *  algorithm to the next @sa FIXME
  55.  *  Implementations of this interface should provide functions for all
  56.  *  the functions listed above.
  57.  */
  58. typedef struct BlastHSPStream BlastHSPStream;
  59. /** Function pointer typedef to create a new BlastHSPStream structure.
  60.  * First argument is a pointer to the structure to be populated (allocated for
  61.  * client implementations), second argument should be typecast'd to the 
  62.  * correct type by user-defined constructor function */
  63. typedef BlastHSPStream* (*BlastHSPStreamConstructor) (BlastHSPStream*, void*);
  64. /** Function pointer typedef to deallocate a BlastHSPStream structure.
  65.  * Argument is the BlastHSPStream structure to free, always returns NULL. */
  66. typedef BlastHSPStream* (*BlastHSPStreamDestructor) (BlastHSPStream*);
  67. /** Function pointer typedef to implement the read/write functionality of the
  68.  * BlastHSPStream. The first argument is the BlastHSPStream structure used, 
  69.  * second argument is the list of HSPs to be saved/read (reading assumes
  70.  * ownership, writing releases ownership) */
  71. typedef int (*BlastHSPStreamMethod) (BlastHSPStream*, BlastHSPList**);
  72. /*****************************************************************************/
  73. /** Structure that contains the information needed for BlastHSPStreamNew to 
  74.  * fully populate the BlastHSPStream structure it returns */
  75. typedef struct BlastHSPStreamNewInfo {
  76.     BlastHSPStreamConstructor constructor; /**< User-defined function to 
  77.                                            initialize a BlastHSPStream 
  78.                                            structure */
  79.     void* ctor_argument;                 /**< Argument to the above function */
  80. } BlastHSPStreamNewInfo;
  81. /** Allocates memory for a BlastHSPStream structure and then invokes the
  82.  * constructor function defined in its first argument, passing the 
  83.  * ctor_argument member of that same structure. If the constructor function
  84.  * pointer is not set, NULL is returned.
  85.  * @param bhsn_info Structure defining constructor and its argument to be
  86.  *        invoked from this function [in]
  87.  */
  88. BlastHSPStream* BlastHSPStreamNew(const BlastHSPStreamNewInfo* bhsn_info);
  89. /** Frees the BlastHSPStream structure by invoking the destructor function set 
  90.  * by the user-defined constructor function when the structure is initialized
  91.  * (indirectly, by BlastHSPStreamNew). If the destructor function pointer is not
  92.  * set, a memory leak could occur.
  93.  * @param hsp_stream BlastHSPStream to free [in]
  94.  * @return NULL
  95.  */
  96. BlastHSPStream* BlastHSPStreamFree(BlastHSPStream* hsp_stream);
  97. /** Standard error return value for BlastHSPStream methods */
  98. extern const int kBlastHSPStream_Error;
  99. /** Standard success return value for BlastHSPStream methods */
  100. extern const int kBlastHSPStream_Success;
  101. /** Return value when the end of the stream is reached (applicable to read
  102.  * method only) */
  103. extern const int kBlastHSPStream_Eof;
  104. /** Invokes the user-specified write function for this BlastHSPStream
  105.  * implementation.
  106.  * @param hsp_stream The BlastHSPStream object [in]
  107.  * @param hsp_list List of HSPs for the HSPStream to keep track of. The caller
  108.  * releases ownership of the hsp_list [in]
  109.  * @return kBlastHSPStream_Success on success, otherwise kBlastHSPStream_Error 
  110.  */
  111. int BlastHSPStreamWrite(BlastHSPStream* hsp_stream, BlastHSPList** hsp_list);
  112. /** Invokes the user-specified read function for this BlastHSPStream
  113.  * implementation.
  114.  * @param hsp_stream The BlastHSPStream object [in]
  115.  * @param hsp_list List of HSPs for the HSPStream to return. The caller
  116.  * acquires ownership of the hsp_list [in]
  117.  * @return kBlastHSPStream_Success on success, kBlastHSPStream_Error, or
  118.  * kBlastHSPStream_Eof on end of stream
  119.  */
  120. int BlastHSPStreamRead(BlastHSPStream* hsp_stream, BlastHSPList** hsp_list);
  121. /*****************************************************************************/
  122. /* The following enumeration and function are only of interest to implementors
  123.  * of this interface */
  124. /** Defines the methods supported by the BlastHSPStream ADT */
  125. typedef enum EMethodName {
  126.     eConstructor,       /**< Constructor for a BlastHSPStream implementation */
  127.     eDestructor,        /**< Destructor for a BlastHSPStream implementation */
  128.     eRead,              /**< Read from the BlastHSPStream */
  129.     eWrite,             /**< Write to the BlastHSPStream */
  130.     eMethodBoundary     /**< Limit to facilitate error checking */
  131. } EMethodName;
  132. /** Union to encapsulate the supported methods on the BlastHSPStream interface
  133.  */
  134. typedef union BlastHSPStreamFunctionPointerTypes {
  135.     /** Used for read/write function pointers */
  136.     BlastHSPStreamMethod method;        
  137.     /** Used for constructor function pointer */
  138.     BlastHSPStreamConstructor ctor;     
  139.     /** Used for destructor function pointer */
  140.     BlastHSPStreamDestructor dtor;      
  141. } BlastHSPStreamFunctionPointerTypes;
  142. /** Sets implementation specific data structure 
  143.  * @param hsp_stream structure to initialize [in]
  144.  * @param data structure to assign to the hsp_stream [in]
  145.  * @return kBlastHSPStream_Error if hsp_stream is NULL else,
  146.  * kBlastHSPStream_Success;
  147.  */
  148. int SetData(BlastHSPStream* hsp_stream, void* data);
  149. /** Gets implementation specific data structure 
  150.  * @param hsp_stream structure from which to obtain the internal data. It is
  151.  * expected that the caller (implementation of BlastHSPStream) knows what type
  152.  * to cast the return value to. [in]
  153.  * @return pointer to internal data structure of the implementation of the
  154.  * BlastHSPStream, or NULL if hsp_stream is NULL
  155.  */
  156. void* GetData(BlastHSPStream* hsp_stream);
  157. /** Use this function to set the pointers to functions implementing the various
  158.  * methods supported in the BlastHSPStream interface 
  159.  * @param hsp_stream structure to initialize [in]
  160.  * @param name method for which a function pointer is being provided [in]
  161.  * @param fnptr_type union containing the pointer to the function specified by
  162.  * name [in]
  163.  * @return kBlastHSPStream_Error if hsp_stream is NULL else,
  164.  * kBlastHSPStream_Success;
  165.  */
  166. int SetMethod(BlastHSPStream* hsp_stream, 
  167.                EMethodName name,
  168.                BlastHSPStreamFunctionPointerTypes fnptr_type);
  169. #ifdef __cplusplus
  170. }
  171. #endif
  172. #endif /* ALGO_BLAST_CORE__BLAST_HSPSTREAM_H */