class ugcs::vsm::File_processor::Stream¶

Overview¶

Stream class which represents opened file. More…

#include <file_processor.h>

class Stream: public ugcs::vsm::Io_stream
{
public:
    // typedefs

    typedef std::shared_ptr<Stream> Ptr;
    typedef std::weak_ptr<Stream> Weak_ptr;
    typedef Reference_guard<Stream::Ptr> Ref;
    typedef Callback_proxy<void, Io_result> Lock_handler;

    // enums

    enum Lock_result;

    // structs

    struct Lock_cb;

    // classes

    class Mode;
    class Native_handle;

    // construction

    Stream(
        File_processor::Ptr processor,
        const std::string& path,
        Mode mode,
        bool maintain_pos,
        Native_handle::Unique_ptr&& native_handle
        );

    // methods

    template <typename... Args>
    static Ptr Create(Args&&... args);

    Offset Get_current_pos() const;
    Offset Seek(Offset pos, bool is_relative = false);
    Operation_waiter Lock(Lock_handler completion_handler, Request_completion_context::Ptr comp_ctx = Request_temp_completion_context::Create(), bool lock = true);
    Operation_waiter Unlock(Lock_handler completion_handler = Make_dummy_callback<void, Io_result>(), Request_completion_context::Ptr comp_ctx = Request_temp_completion_context::Create());
};

// direct descendants

class Stream;

Inherited Members¶

public:
    // typedefs

    typedef std::shared_ptr<Io_stream> Ptr;
    typedef std::weak_ptr<Io_stream> Weak_ptr;
    typedef Reference_guard<Io_stream::Ptr> Ref;
    typedef int64_t Offset;
    typedef Callback_proxy<void, Io_result> Write_handler;
    typedef Callback_proxy<void, Io_buffer::Ptr, Io_result> Read_handler;
    typedef Callback_proxy<void> Close_handler;

    // enums

    enum State;
    enum Type;

    // fields

    static const Offset OFFSET_NONE;
    static const Offset OFFSET_END;

    // methods

    template <typename... Args>
    static Ptr Create(Args&&... args);

    static const char* Io_result_as_char(const Io_result res);
    void Add_ref();
    void Release_ref();
    Operation_waiter Write(Io_buffer::Ptr buffer, Offset offset, Write_handler completion_handler = Make_dummy_callback<void, Io_result>(), Request_completion_context::Ptr comp_ctx = Request_temp_completion_context::Create());
    Operation_waiter Write(Io_buffer::Ptr buffer, Write_handler completion_handler = Make_dummy_callback<void, Io_result>(), Request_completion_context::Ptr comp_ctx = Request_temp_completion_context::Create());

    Operation_waiter Read(
        size_t max_to_read,
        size_t min_to_read,
        Offset offset,
        Read_handler completion_handler = Make_dummy_callback<void, Io_buffer::Ptr, Io_result>(),
        Request_completion_context::Ptr comp_ctx = Request_temp_completion_context::Create()
        );

    Operation_waiter Read(
        size_t max_to_read,
        size_t min_to_read = 1,
        Read_handler completion_handler = Make_dummy_callback<void, Io_buffer::Ptr, Io_result>(),
        Request_completion_context::Ptr comp_ctx = Request_temp_completion_context::Create()
        );

    Operation_waiter Close(Close_handler completion_handler = Make_dummy_callback<void>(), Request_completion_context::Ptr comp_ctx = Request_temp_completion_context::Create());
    State Get_state() const;
    bool Is_closed() const;
    std::string Get_name() const;
    Type Get_type() const;

Detailed Documentation¶

Stream class which represents opened file.

Typedefs¶

typedef std::shared_ptr<Stream> Ptr

Pointer type.

typedef std::weak_ptr<Stream> Weak_ptr

Pointer type.

typedef Reference_guard<Stream::Ptr> Ref

Reference type.

typedef Callback_proxy<void, Io_result> Lock_handler

Default prototype for lock operation completion handler.

Construction¶

Stream(
    File_processor::Ptr processor,
    const std::string& path,
    Mode mode,
    bool maintain_pos,
    Native_handle::Unique_ptr&& native_handle
    )

Construct file stream.

Parameters:

processor	Associated processor instance.
path	File path.
mode	Parsed file opening mode.
maintain_pos	Indicates whether file position maintenance is required. See File_processor::Open.
native_handle	Native handle to be used for stream operations.

Methods¶

template <typename... Args>
static Ptr Create(Args&&... args)

Create an instance.

Offset Get_current_pos() const

Get current position in the stream.

This method has meaning only file position is maintained by the stream.

Returns:

Current position in the stream.

Offset Seek(Offset pos, bool is_relative = false)

Set new current position for the stream.

In case the stream does not maintain the current position, this operation does nothing. Be aware that seeking result is undefined if read or write operation is in progress.

Parameters:

pos	New current position value.
is_relative	Indicates that position is set relatively to the current position value.
Invalid_param_exception	if the resulted position is invalid (e.g. negative).

Returns:

New absolute current position value.

Operation_waiter Lock(Lock_handler completion_handler, Request_completion_context::Ptr comp_ctx = Request_temp_completion_context::Create(), bool lock = true)

Put an exclusive lock on file.

On Windows it’s mandatory lock on first byte of file implemented via LockFileEx() call. On Linux it’s advisory lock implemented via flock() call. File can be unlocked via Unlock() call or via Close().

NOTE: No double lock supported: Stream can be locked again only after successful Unlock() operation. I.e. subsequent Lock on the same stream will fail until Unlock() is called and unlock completion is delivered.

Parameters:

completion_handler	User specified completion handler.
comp_ctx	User specified completion context.
lock	true: lock operation, false: unlock operation.

Returns:

Operation_waiter which can be used to wait, or set timeout or cancel for pending lock operation.

Operation_waiter Unlock(Lock_handler completion_handler = Make_dummy_callback<void, Io_result>(), Request_completion_context::Ptr comp_ctx = Request_temp_completion_context::Create())

Remove lock from file.

On Windows it unlocks on first byte of file implemented via UnlockFile() call. On Linux it is implemented via flock() call.

Parameters:

completion_handler	User specified completion handler.
comp_ctx	User specified completion context.

Returns:

Operation_waiter which can be used to wait for pending unlock operation to complete.

class ugcs::vsm::File_processor::Native_controller

enum ugcs::vsm::File_processor::Stream::Lock_result