ncbifile.hpp

ncbi源码

/////////////////////////////////////////////////////////////////////////////
///
/// Utility algorithm scans the provided directories using iterators
/// finds files to match the masks and stores all found files in 
/// the container object.
///

template<class TContainer, class It1, class It2>
void FindFiles(TContainer&      out, 
               It1  first_path, It1 last_path, 
               It2  first_mask, It2 last_mask,
               TFindFiles           flags = fFF_Default)
{
    CFindFileNamesFunc<TContainer> func(out);
    FindFiles(first_path, last_path, 
              first_mask, last_mask, func, flags);
}



/////////////////////////////////////////////////////////////////////////////
///
/// fwd-decl of struct containing OS-specific mem.-file handle.

struct SMemoryFileHandle;



/////////////////////////////////////////////////////////////////////////////
///
/// CMemoryFile --
///
/// Define class for support file memory mapping.

class NCBI_XNCBI_EXPORT CMemoryFile
{
public:
    /// Which operations are permitted in memory map file.
    typedef enum {
        eMMP_Read,            ///< Data can be read
        eMMP_Write,           ///< Data can be written
        eMMP_ReadWrite    ///< Data can be read and written
    } EMemMapProtect;

    /// Whether to share changes or not.
    typedef enum {
        eMMS_Shared,      ///< Changes are shared.
        eMMS_Private      ///< Changes are private.
    } EMemMapShare;

    /// Constructor.
    ///
    /// Initialize the memory mapping on file "file_name".  Throws an
    /// exception on error.
    /// @param filename
    ///   Name of file to map to memory.
    /// @param protect_attr
    ///   Specify operations permitted on memory mapped file.
    /// @param share_attr
    ///   Specify if change to memory mapped file can be shared or not.
    /// @sa
    ///   EMemMapProtect, EMemMapShare
    CMemoryFile(const string&  file_name,
                EMemMapProtect protect_attr = eMMP_Read,
                EMemMapShare   share_attr   = eMMS_Private);

    /// Destructor.
    ///
    /// Calls Unmap() and cleans up memory mapped file.
    ~CMemoryFile(void);

    /// Check if memory-mapping is supported by the C++ Toolkit on this
    /// platform.
    static bool IsSupported(void);

    /// Get pointer to beginning of data.
    ///
    /// @return
    ///    - Pointer to start of data, or
    ///    - NULL if mapped to a file of zero length, or if unmapped already.
    void* GetPtr(void) const;

    /// Get size of the mapped area.
    ///
    /// @return
    ///   - Size in bytes of mapped area, or
    ///   - -1 if unmapped already.
    Int8 GetSize(void) const;

    /// Flush by writing all modified copies of memory pages to the
    /// underlying file.
    ///
    /// NOTE: By default data will be flushed in Unmap() or destructor.
    bool Flush(void) const;

    /// Unmap file if mapped.
    ///
    /// @return
    ///   TRUE on success; or FALSE on error.
    bool Unmap(void);

    /// What type of data access pattern will be used for mapped region.
    ///
    /// Advises the VM system that the a certain region of user mapped memory 
    /// will be accessed following a type of pattern. The VM system uses this 
    /// information to optimize work with mapped memory.
    ///
    /// NOTE: Now works on UNIX platform only.
    typedef enum {
        eMMA_Normal,      ///< No further special treatment
        eMMA_Random,      ///< Expect random page references
        eMMA_Sequential,  ///< Expect sequential page references
        eMMA_WillNeed,    ///< Will need these pages
        eMMA_DontNeed     ///< Don't need these pages
    } EMemMapAdvise;

    /// Advise on memory map usage.
    ///
    /// @param advise
    ///   One of the values in EMemMapAdvise that advises on expected
    ///   usage pattern.
    /// @return
    ///   - TRUE, if memory advise operation successful. Always return
    ///   TRUE if memory advise not implemented such as on Windows system.
    ///   - FALSE, if memory advise operation not successful.
    /// @sa
    ///   EMemMapAdvise, MemMapAdviseAddr
    bool MemMapAdvise(EMemMapAdvise advise);

    /// Advise on memory map usage for specified region.
    ///
    /// @param addr
    ///   Address of memory region whose usage is being advised.
    /// @param len
    ///   Length of memory region whose usage is being advised.
    /// @param advise
    ///   One of the values in EMemMapAdvise that advises on expected
    ///   usage pattern.
    /// @return
    ///   - TRUE, if memory advise operation successful. Always return
    ///   TRUE if memory advise not implemented such as on Windows system.
    ///   - FALSE, if memory advise operation not successful.
    /// @sa
    ///   EMemMapAdvise, MemMapAdvise
    static bool MemMapAdviseAddr(void* addr, size_t len, EMemMapAdvise advise);

private:
    /// Helper method to map file to memory.
    ///
    /// @param filename
    ///   Name of file to map to memory.
    /// @param protect_attr
    ///   Specify operations permitted on memory mapped file.
    /// @param share_attr
    ///   Specify if change to memory mapped file can be shared or not.
    /// @sa
    ///   EMemMapProtect, EMemMapShare
    void x_Map(const string&  file_name,
               EMemMapProtect protect_attr,
               EMemMapShare   share_attr);

private:
    SMemoryFileHandle*  m_Handle;   ///< Memory file handle
    Int8                m_Size;     ///< Size (in bytes) of the mapped area
    void*               m_DataPtr;  ///< Pointer to the begining of mapped
                                    ///< data
};


/* @} */



//////////////////////////////////////////////////////////////////////////////
//
// Inline
//


// CDirEntry

#ifndef NCBI_OS_MAC
inline
void CDirEntry::Reset(const string& path)
{
    m_Path = DeleteTrailingPathSeparator(path);
}

inline
string CDirEntry::GetPath(void) const
{
    return m_Path;
}
#endif

inline
string CDirEntry::GetDir(void) const
{
    string dir;
    SplitPath(GetPath(), &dir);
    return dir;
}

inline
string CDirEntry::GetName(void) const
{
    string title, ext;
    SplitPath(GetPath(), 0, &title, &ext);
    return title + ext;
}

inline
string CDirEntry::GetBase(void) const
{
    string base;
    SplitPath(GetPath(), 0, &base);
    return base;
}

inline
string CDirEntry::GetExt(void) const
{
    string ext;
    SplitPath(GetPath(), 0, 0, &ext);
    return ext;
}

inline
bool CDirEntry::IsFile(EFollowLinks follow) const
{
    return GetType(follow) == eFile;
}

inline
bool CDirEntry::IsDir(EFollowLinks follow) const
{
    return GetType(follow) == eDir;
}

inline
bool CDirEntry::Exists(void) const
{
    return GetType() != eUnknown;
}


// CFile

inline
bool CFile::Exists(void) const
{
    return IsFile();
}


// CDir

inline
bool CDir::Exists(void) const
{
    return IsDir();
}


// CMemoryFile

inline
void* CMemoryFile::GetPtr(void) const
{
    return m_DataPtr;
}

inline
Int8 CMemoryFile::GetSize(void) const
{
    return m_Size;
}


END_NCBI_SCOPE


/*
 * ===========================================================================
 * $Log: ncbifile.hpp,v $
 * Revision 1000.5  2004/06/01 19:08:05  gouriano
 * PRODUCTION: UPGRADED [GCC34_MSVC7] Dev-tree R1.42
 *
 * Revision 1.42  2004/05/18 16:51:25  ivanov
 * Added CDir::GetTmpDir()
 *
 * Revision 1.41  2004/04/29 16:18:58  ivanov
 * operator== defined only for MAC OS
 *
 * Revision 1.40  2004/04/29 16:14:03  kuznets
 * Removed unnecessary typename
 *
 * Revision 1.39  2004/04/29 15:14:17  kuznets
 * + Generic FindFile algorithm capable of recursive searches
 * CDir::GetEntries received additional parameter to ignore self
 * recursive directory entries (".", "..")
 *
 * Revision 1.38  2004/04/28 19:04:16  ucko
 * Give GetType(), IsFile(), and IsDir() an optional EFollowLinks
 * parameter (currently only honored on Unix).
 *
 * Revision 1.37  2004/03/17 15:39:37  ivanov
 * CFile:: Fixed possible race condition concerned with temporary file name
 * generation. Added ETmpFileCreationMode enum. Fixed GetTmpName[Ex] and
 * CreateTmpFile[Ex] class methods.
 *
 * Revision 1.36  2004/03/11 22:16:52  vakatov
 * Cosmetics
 *
 * Revision 1.35  2004/01/05 21:41:55  gorelenk
 * += Exception throwing in CDirEntry::CreateRelativePath()
 *
 * Revision 1.34  2004/01/05 20:06:44  gorelenk
 * + CDirEntry::CreateRelativePath()
 *
 * Revision 1.33  2003/11/28 16:23:03  ivanov
 * + CDirEntry::SetTime()
 *
 * Revision 1.32  2003/11/05 16:27:18  kuznets
 * +FindFile template algorithm
 *
 * Revision 1.31  2003/11/05 15:35:44  kuznets
 * Added CDir::GetEntries() based on set of masks
 *
 * Revision 1.30  2003/10/23 12:11:37  ucko
 * Drop <memory> (now unneeded, and should have gone to ncbifile.cpp anyway)
 *
 * Revision 1.29  2003/10/23 03:18:53  ucko
 * +<memory> for auto_ptr
 *
 * Revision 1.28  2003/10/08 15:44:53  ivanov
 * Added CDirEntry::DeleteTrailingPathSeparator()
 *
 * Revision 1.27  2003/10/01 14:32:09  ucko
 * +EFollowLinks
 *
 * Revision 1.26  2003/09/30 15:08:28  ucko
 * Reworked CDirEntry::NormalizePath, which now handles .. correctly in
 * all cases and optionally resolves symlinks (on Unix).
 *
 * Revision 1.25  2003/09/16 15:18:13  ivanov
 * + CDirEntry::NormalizePath()
 *
 * Revision 1.24  2003/08/29 16:56:27  ivanov
 * Removed commit about unsafe GetTmpName() and CreateTmpFile() functions in the MT env
 *
 * Revision 1.23  2003/08/08 13:35:29  siyan
 * Changed GetTmpNameExt to GetTmpNameEx, as this is the more appropriate name.
 *
 * Revision 1.22  2003/08/06 13:45:35  siyan
 * Document changes.
 *
 * Revision 1.21  2003/05/29 17:21:31  gouriano
 * added CreatePath() which creates directories recursively
 *
 * Revision 1.20  2003/03/31 16:54:25  siyan
 * Added doxygen support
 *
 * Revision 1.19  2003/02/05 22:07:32  ivanov
 * Added protect and sharing parameters to the CMemoryFile constructor.
 * Added CMemoryFile::Flush() method.
 *
 * Revision 1.18  2003/01/16 13:03:47  dicuccio
 * Added CDir::GetCwd()
 *
 * Revision 1.17  2002/12/18 22:53:21  dicuccio
 * Added export specifier for building DLLs in windows.  Added global list of
 * all such specifiers in mswin_exports.hpp, included through ncbistl.hpp
 *
 * Revision 1.16  2002/07/15 18:17:51  gouriano
 * renamed CNcbiException and its descendents
 *
 * Revision 1.15  2002/07/11 19:21:58  ivanov
 * Added CMemoryFile::MemMapAdvise[Addr]()
 *
 * Revision 1.14  2002/07/11 14:17:54  gouriano
 * exceptions replaced by CNcbiException-type ones
 *
 * Revision 1.13  2002/06/07 16:11:09  ivanov
 * Chenget GetTime() -- using CTime instead time_t, modification time by default
 *
 * Revision 1.12  2002/06/07 15:20:41  ivanov
 * Added CDirEntry::GetTime()
 *
 * Revision 1.11  2002/04/11 20:39:18  ivanov
 * CVS log moved to end of the file
 *
 * Revision 1.10  2002/04/01 18:49:07  ivanov
 * Added class CMemoryFile
 *
 * Revision 1.9  2002/01/24 22:17:40  ivanov
 * Changed CDirEntry::Remove() and CDir::Remove()
 *
 * Revision 1.8  2002/01/10 16:46:09  ivanov
 * Added CDir::GetHome() and some CDirEntry:: path processing functions
 *
 * Revision 1.7  2001/12/26 20:58:23  juran
 * Use an FSSpec* member instead of an FSSpec, so a forward declaration can 
 * be used.
 * Add copy constructor and assignment operator for CDirEntry on Mac OS,
 * thus avoiding memberwise copy which would blow up upon deleting the 
 * pointer twice.
 *
 * Revision 1.6  2001/12/13 20:14:34  juran
 * Add forward declaration of struct FSSpec for Mac OS.
 *
 * Revision 1.5  2001/11/19 18:07:38  juran
 * Change Contents() to GetEntries().
 * Implement MatchesMask().
 *
 * Revision 1.4  2001/11/15 16:30:46  ivanov
 * Moved from util to corelib
 *
 * Revision 1.3  2001/11/01 21:02:18  ucko
 * Fix to work on non-MacOS platforms again.
 *
 * Revision 1.2  2001/11/01 20:06:49  juran
 * Replace directory streams with Contents() method.
 * Implement and test Mac OS platform.
 *
 * Revision 1.1  2001/09/19 13:04:18  ivanov
 * Initial revision
 * ===========================================================================
 */

#endif  /* CORELIB__NCBIFILE__HPP */