UTBufferedFile.h

Go to the documentation of this file.

//==================================================================================================
// Copyright (C) 2010  Brian Tietz    sdbtietz at yahoo dot com
//
// This program is free software; you can redistribute it and/or modify it under the terms of the
// GNU General Public License as published by the Free Software Foundation, version 2.0 of the
// License.
//
// This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without
// even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
// General Public License for more details.
//
// You should have received a copy of the GNU General Public License along with this program; if
// not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
// 02110-1301, USA.
//
// For commercial software, the copyright holder (Brian Tietz, email sdbtietz at yahoo dot com)
// reserves the right and is willing to waive the proprietary source code disclosure aspects of that
// license as applied to the UT library in exchange for either substantial contributions to the
// development of the UT library or other forms of compensation.  Any such waiver must be
// established in writing between the copyright holder and the commercial entity obtaining such a
// waiver.
//==================================================================================================


#ifndef _UT_BUFFERED_FILE_H_
#define _UT_BUFFERED_FILE_H_


//==================================================================================================
//=== Project headers
//==================================================================================================
#include "UTFile.h"
#include "UTLists.h"


//==================================================================================================
//=== Constants
//==================================================================================================

// \cond DOXYGEN_DOCUMENT_NEVER

enum buffered_file_state_t
{
    eBFS_closed,
    eBFS_opening,
    eBFS_idle,
    eBFS_write_work_buf,
    eBFS_read_work_buf,
    eBFS_write_block,
    eBFS_read_block,
    eBFS_preload_block
};

// \endcond


//==================================================================================================
//=== Forward name declarations
//==================================================================================================
class BufferedFileBlock_t;


//==================================================================================================
class UT_EXPORT BufferedFile_t
//==================================================================================================
:   public File_t,
    public Task_t
{
    //----------------------------------------------------------------------------------------------
    public:
    //----------------------------------------------------------------------------------------------
                        BufferedFile_t(int buffer_size = 8192);

    virtual             ~BufferedFile_t();

    virtual Status_t    Open(   const Path_t& path,
                                int flags,
                                mode_t permissions = 0,
                                MessageDestination_t<FileReadCompleteMessage_t>* read_dest = NULL,
                                MessageDestination_t<FileWriteCompleteMessage_t>* write_dest = NULL,
                                MessageDestination_t<FileOpenCompleteMessage_t>* open_dest = NULL );

    inline Status_t     Open(   const utf8* path,
                                int flags,
                                mode_t permissions = 0,
                                MessageDestination_t<FileReadCompleteMessage_t>* read_dest = NULL,
                                MessageDestination_t<FileWriteCompleteMessage_t>* write_dest = NULL,
                                MessageDestination_t<FileOpenCompleteMessage_t>* open_dest = NULL );

    inline Status_t     Open(   stringliteral* path,
                                int flags,
                                mode_t permissions = 0,
                                MessageDestination_t<FileReadCompleteMessage_t>* read_dest = NULL,
                                MessageDestination_t<FileWriteCompleteMessage_t>* write_dest = NULL,
                                MessageDestination_t<FileOpenCompleteMessage_t>* open_dest = NULL );

    virtual Status_t    Read( byte* buffer, int bytes_to_read, bool force_read_all = true );

    virtual Status_t    ReadLine(out String_t* line);

    virtual Status_t    Write(  const byte* buffer,
                                int bytes_to_write,
                                bool force_write_all = true );

    virtual Status_t    WriteLine(  const String_t& line,
                                    line_ending_type_t line_ending = eLINEENDING_native );

    virtual Status_t    WriteLine(  const utf8* line,
                                    line_ending_type_t line_ending = eLINEENDING_native );

    virtual Status_t    WriteLine(  stringliteral* line,
                                    line_ending_type_t line_ending = eLINEENDING_native );

    virtual Status_t    Size(out fileoff_t* size);

    virtual Status_t    Position(out fileoff_t* position);

    virtual Status_t    Seek(fileoff_t position);

    virtual Status_t    Flush();

    virtual Status_t    Close();

    //----------------------------------------------------------------------------------------------
    protected:
    //----------------------------------------------------------------------------------------------
    virtual Status_t    AsyncOpenComplete();

    #if LOG_FILE_OPS
    virtual void        AppendStateInfo(String_t* state) const;
    #endif

    //----------------------------------------------------------------------------------------------
    private:
    //----------------------------------------------------------------------------------------------
    void                    RunStateMachine(bool force_all);
    void                    RunReadStateMachine(bool force_all);
    void                    RunWriteStateMachine(bool force_all);
    void                    CheckSeekPastEndOfFile( fileoff_t pos, bool force_all );
    BufferedFileBlock_t*    FindBlock( fileoff_t pos, bool will_use );
    void                    ReadFromBlock( BufferedFileBlock_t* block, bool force_all );
    void                    AssessPreloadNext(  BufferedFileBlock_t* current_block,
                                                int offset_into_block );
    void                    LoadNewBlock(   fileoff_t pos,
                                            bool force_all,
                                            bool preload,
                                            BufferedFileBlock_t* avoid );
    void                    FillBlockGap(   BufferedFileBlock_t* block,
                                            int will_read_from,
                                            int will_read_to,
                                            int will_overwrite_from,
                                            int will_overwrite_to,
                                            int already_overwrote_from,
                                            int already_overwrote_to,
                                            bool force_all );
    void                    WriteToBlock( BufferedFileBlock_t* block, bool force_all );
    void                    AllocateAndWriteToNewBlock(bool force_all);
    BufferedFileBlock_t*    RecycleExistingBuffer(  BufferedFileBlock_t* avoid,
                                                    bool force_recycling );
    BufferedFileBlock_t*    RecycleImmediatelyAvailableBuffer(BufferedFileBlock_t* avoid);
    void                    WriteAllDirtyBlocks( fileoff_t before, bool force_all );
    void                    CompleteIO(bool force_all);
    void                    UpdateBlockExtents( BufferedFileBlock_t* block,
                                                int offset_into_block, 
                                                int length,
                                                bool wrote_to_block,
                                                bool wrote_from_block );
    Status_t                PrepReadLineErrorReturn( bool read_any, int partial_utf8_sequence_len );
    error_code_t            ReadLineFromBlock(  BufferedFileBlock_t* block,
                                                String_t* line,
                                                bool only_check_for_lf,
                                                utf8* partial_utf8_sequence,
                                                int* partial_utf8_sequence_len,
                                                int* offset_into_block );
    bool                    ReadLineWillWriteTempZero(  BufferedFileBlock_t* block,
                                                        int offset_into_block );

    //----------------------------------------------------------------------------------------------
    private:
    //----------------------------------------------------------------------------------------------
    int                                                 m_block_size;
    int                                                 m_max_blocks;
    bool                                                m_async_io_allowed;
    fileoff_t                                           m_pos;
    fileoff_t                                           m_size;
    Status_t                                            m_status;

    buffered_file_state_t                               m_state;

    byte*                                               m_caller_buf;
    int                                                 m_caller_bytes;
    bool                                                m_caller_write;
    byte*                                               m_work_in_caller_buf;
    int                                                 m_work_in_caller_buf_bytes;
    bool                                                m_notify_caller_when_state_machine_done;

    BufferedFileBlock_t*                                m_work_block;
    int                                                 m_work_block_io_offset;
    int                                                 m_work_io_bytes;

    LinkedList_t<BufferedFileBlock_t>                   m_blocks;
    int                                                 m_contiguous_read_bytes;

    MessageDestination_t<FileReadCompleteMessage_t>     m_owner_read_dest;
    MessageDestination_t<FileWriteCompleteMessage_t>    m_owner_write_dest;

    //----------------------------------------------------------------------------------------------
    private:
    //----------------------------------------------------------------------------------------------
    void ReadCompleteReceived(const FileReadCompleteMessage_t* message);
    MessageReceiver_t< BufferedFile_t, FileReadCompleteMessage_t >  m_ReadCompleteReceiver;

    void WriteCompleteReceived(const FileWriteCompleteMessage_t* message);
    MessageReceiver_t< BufferedFile_t, FileWriteCompleteMessage_t > m_WriteCompleteReceiver;

    void IOCompleteReceived(    const FileReadCompleteMessage_t* read_msg,
                                const FileWriteCompleteMessage_t* write_msg );

    #if LOG_FILE_OPS
    void    DebugBufferedFileDumpState(out String_t* string);
    void    DebugBufferedFileDumpStateToString(out String_t* string);
    #endif
};


// \cond DOXYGEN_DOCUMENT_NEVER

//==================================================================================================
class BufferedFileBlock_t
//==================================================================================================
: public LinkedListNode_t<BufferedFileBlock_t>
{
    public:
    fileoff_t       pos;
    int             valid_from;
    int             valid_to;
    int             need_write_from;
    int             need_write_to;
    inline byte*    Data();
};




//==================================================================================================
//==================================================================================================
//===
//=== Inline function implementations
//===
//==================================================================================================
//==================================================================================================
inline Status_t
BufferedFile_t::Open(   const utf8* path,
                        int flags,
                        mode_t permissions,
                        MessageDestination_t<FileReadCompleteMessage_t>* read_dest,
                        MessageDestination_t<FileWriteCompleteMessage_t>* write_dest,
                        MessageDestination_t<FileOpenCompleteMessage_t>* open_dest )
{
    // Using the stringliteral form allows the temporary Path_t to borrow the caller's utf8* rather
    // than copying it
    return Open(    Path_t( reinterpret_cast<stringliteral*>(path) ),
                    flags,
                    permissions,
                    read_dest,
                    write_dest,
                    open_dest );
}


inline Status_t
BufferedFile_t::Open(   stringliteral* path,
                        int flags,
                        mode_t permissions,
                        MessageDestination_t<FileReadCompleteMessage_t>* read_dest,
                        MessageDestination_t<FileWriteCompleteMessage_t>* write_dest,
                        MessageDestination_t<FileOpenCompleteMessage_t>* open_dest )
{
    return Open( Path_t(path), flags, permissions, read_dest, write_dest, open_dest );
}


inline byte*
BufferedFileBlock_t::Data()
{
    return reinterpret_cast<byte*>(this) + sizeof(BufferedFileBlock_t);
}


// \endcond

#endif // _UT_BUFFERED_FILE_H_