PosixDescriptor Class Reference

Abstraction of a POSIX descriptor. More...

#include <PosixDescriptor.hpp>

Inheritance diagram for PosixDescriptor:

Classes
struct	job
	Single asynchronous operation. More...
class	shared_queue
	Class for synchronization between the main thread and the worker thread. More...
class	Worker
	Worker thread to perform asynchronous operations. More...

Public Member Functions
virtual	~PosixDescriptor ()
	Destructor.
void	async_read (void(*handler)(Buffer *b, size_t size), Buffer *b, size_t size)
	Run asynchronous read operation.
void	async_read (void(*handler)(void *b, size_t size), void *b, size_t size)
	Run asynchronous read operation.
void	async_write (void(*handler)(Buffer *b, size_t size), Buffer *b, size_t size)
	Run asynchronous write operation.
void	async_write (void(*handler)(void *b, size_t size), void *b, size_t size)
	Run asynchronous write operation.
int	read (Buffer *b, size_t size)
	Method to read from the descriptor and fill a buffer.
int	read (void *p, size_t size)
	Method to read from the descriptor.
int	write (Buffer *b, size_t size)
	Method to write data in a buffer to the descriptor.
int	write (const void *p, size_t size)
	Method to write to the descriptor.
int	write (const std::string &s)
	Method to write a string to the descriptor.
virtual void	close ()
	Method to close the descriptor.
int	getDescriptorNumber () const
	Method to get descriptor number.
	PosixDescriptor (const PosixDescriptor &src)
	Copy constructor.
PosixDescriptor &	operator= (const PosixDescriptor &src)
	Assignment operator.
bool	flush ()
	Method to flush this specific descriptor.
int	ioctl (int request)
	Ioctl on the file descriptor.
int	ioctl (int request, void *argp)
	Ioctl on the file descriptor.

Protected Member Functions
int	do_read (void *p, size_t size)
	Low-level read.
int	do_write (const void *p, size_t size)
	Low-level write.
	PosixDescriptor ()
	Constructor.

Protected Attributes
int	fd_
	Number of the file descriptor.

Private Member Functions
	PosixDescriptor (int fd)
	Private constructor used by derived classes.

Private Attributes
Worker *	worker_
	Pointer to the worker that performs asynchronous operations.
shared_queue *	queue_
	Pointer to the shared_queue for synchronization with the worker thread.
bool	worker_started_
	If the worker thread has been already started.

Friends
class	Pipe
class	AsyncThread

Detailed Description

Abstraction of a POSIX descriptor.

This is an abstract class for the concept of Posix descriptor. The descriptor can correspond to a file (class FileDescriptor) or to a socket (class StreamSocketServerDescriptor).

Definition at line 58 of file PosixDescriptor.hpp.

Constructor & Destructor Documentation

PosixDescriptor ( int  fd )

inlineprivate

Private constructor used by derived classes.

It allocates queue_ and worker_.

Parameters

fd	File descriptor number returned by open(), socket(), accept(), etc.

Definition at line 352 of file PosixDescriptor.hpp.

                               : queue_(0), worker_started_(false), fd_(fd) {
                queue_ = new shared_queue;
                worker_ = new Worker (queue_, this);
        }

PosixDescriptor ( )

inlineprotected

Constructor.

It allocates queue_ and worker_.

Definition at line 376 of file PosixDescriptor.hpp.

                         : queue_(0), worker_started_(false), fd_(-1) {
                queue_ = new shared_queue;
                worker_ = new Worker (queue_, this);
        }

virtual ~PosixDescriptor ( )

inlinevirtual

Destructor.

It closes the file descriptor and deallocates queue_ and worker_.

Definition at line 388 of file PosixDescriptor.hpp.

                                   {
                DEBUG("Destroying descriptor...");
                DEBUG("Closing desciptor...");
                close();
                DEBUG("delete thread...");
                delete(worker_);
                delete(queue_);

                DEBUG("Descriptor succesfully destroyed. Let's move on!");
        }

Here is the call graph for this function:

PosixDescriptor ( const PosixDescriptor &  src )

inline

Copy constructor.

The copy constructor is called to copy an existing object to another object that is being constructed. Examples:

PosixDescriptor p1;
PosixDescriptor p2 = p1;
PosixDesscriptor p3 (p1);

It allocates queue_ and worker_.

Exceptions

runtime_error

if the ::dup() returns an error

Definition at line 546 of file PosixDescriptor.hpp.

                                                   : queue_(0), worker_started_(false) {
                fd_ = ::dup(src.fd_);
                if (fd_ < 0) {
                        ERROR("Bad file descriptor");
                        throw std::runtime_error("PosixDescriptor: error in copy constructor");
                }
                DEBUG("Creating worker (stopped)");
                queue_ = new shared_queue;
                worker_ = new Worker (queue_, this);
        }

Member Function Documentation

void async_read ( void(*)(Buffer *b, size_t size)  handler, Buffer *  b, size_t  size  )

inline

Run asynchronous read operation.

This method schedules an asynchronous read operation. The operation is internally run on a different thread.

Parameters

handler	Function to be run when the read operation has finished. This function will have two parameters: a pointer to the Buffer where data has been saved, and the number of bytes actually read.
b	Pointer to the Buffer to be provided to the handler function as argument
size	Number of bytes to be read

Definition at line 413 of file PosixDescriptor.hpp.

                        {
                DEBUG("async_read() called!");
                if (!worker_started_){
                        worker_->start();
                        worker_started_ = true;
                }
                worker_->startAsyncOperation(true, handler, b, size);
        }

Here is the call graph for this function:

void async_read ( void(*)(void *b, size_t size)  handler, void *  b, size_t  size  )

inline

Run asynchronous read operation.

This method schedules an asynchronous read operation. The operation is internally run on a different thread.

Parameters

handler	Function to be run when the read operation has finished. This function will have two parameters: a void* where data has been saved, and the number of bytes actually read.
b	Pointer to be provided to the handler function as argument
size	Number of bytes to be read

Definition at line 437 of file PosixDescriptor.hpp.

                        {
                DEBUG("async_read() called!");
                if (!worker_started_){
                        worker_->start();
                        worker_started_ = true;
                }
                worker_->startAsyncOperation(true, handler, b, size);
        }

Here is the call graph for this function:

void async_write ( void(*)(Buffer *b, size_t size)  handler, Buffer *  b, size_t  size  )

inline

Run asynchronous write operation.

This method schedules an asynchronous write operation. The operation is internally run on a different thread.

Parameters

handler	Function to be run when the write operation has finished. This function will have two parameters: a pointer to the Buffer where original data was stored, and the number of bytes actually written.
b	Pointer to the Buffer to be provided to the handler function as argument
size	Number of bytes to be written.

Definition at line 462 of file PosixDescriptor.hpp.

                        {
                if (!worker_started_){
                        worker_->start();
                        worker_started_ = true;
                }
                worker_->startAsyncOperation(false, handler, b, size);
        }

Here is the call graph for this function:

void async_write ( void(*)(void *b, size_t size)  handler, void *  b, size_t  size  )

inline

Run asynchronous write operation.

This method schedules an asynchronous write operation. The operation is internally run on a different thread.

Parameters

handler	Function to be run when the write operation has finished. This function will have two parameters: a void* where original data was stored, and the number of bytes actually written.
b	Pointer to be provided to the handler function as argument
size	Number of bytes to be written

Definition at line 485 of file PosixDescriptor.hpp.

                        {
                if (!worker_started_){
                        worker_->start();
                        worker_started_ = true;
                }
                worker_->startAsyncOperation(false, handler, b, size);
        }

Here is the call graph for this function:

virtual void close ( )

inlinevirtual

Method to close the descriptor.

Note: currently there is no method to re-open the descriptor. In case the worker thread has been started, it signals the worker that it must not block on wait anymore (through set_flush_and_close()); then it unblocks the worker (through signal_not_empty()).

Reimplemented in DgramSocketServerDescriptor.

Definition at line 510 of file PosixDescriptor.hpp.

                                   {
                if (worker_started_){
                        DEBUG("Flushing pending data...")
                        queue_->set_flush_and_close();
                        queue_->signal_not_empty();
                        queue_->wait_empty();
                        worker_->waitForTermination();
                }
                ::close(fd_);
        }

Here is the call graph for this function:

Here is the caller graph for this function:

int do_read ( void *  buffer, size_t  size  )

protected

Low-level read.

This method is private because it is meant to be used through the other read() methods. Note: it can block the caller, because it continues reading until the given number of bytes have been read.

Parameters

buffer	Pointer to the buffer where read bytes must be stored
size	Number of bytes to be read

Exceptions

runtime_error

if the ::read() returns an error

Returns

The number of actually read bytes or -1 in case of error

Definition at line 156 of file PosixDescriptor.cpp.

{
        size_t remaining = size;
        while (remaining > 0) {
                ssize_t ret = ::read (fd_, ((char*)buffer)+(size-remaining),
                    remaining);
                if (ret == 0)
                        // End of file reached
                        break;
                else if (ret < 0) {
                        throw std::runtime_error ("Read error");
                        return -1;
                }
                remaining -= ret;
        }
        return (size-remaining);
}

Here is the call graph for this function:

Here is the caller graph for this function:

int do_write ( const void *  buffer, size_t  size  )

protected

Low-level write.

This method is private because it is meant to be used through the other write() methods. Note: it can block the caller, because it continues writing until the given number of bytes have been written.

Parameters

buffer	Pointer to the buffer containing bytes to be written
size	Number of bytes to be written

Exceptions

runtime_error

if the ::write() returns 0 or an error

Returns

The number of actually written bytes or -1 in case of error

Definition at line 224 of file PosixDescriptor.cpp.

{
        size_t remaining = size;
        while (remaining > 0) {
                ssize_t ret = ::write (fd_,
                    ((char*)buffer)+(size-remaining), remaining);
                if (ret == 0)
                        // Cannot write more
                        break;
                else if (ret < 0) {
                        throw std::runtime_error ("Write error");
                        return -1;
                }
                remaining -= ret;
        }
        return (size-remaining);
}

Here is the call graph for this function:

Here is the caller graph for this function:

bool flush ( )

inline

Method to flush this specific descriptor.

Definition at line 582 of file PosixDescriptor.hpp.

                           {
                if (syncfs(fd_) < 0)
                        return false;
                else
                        return true;
        }

int getDescriptorNumber ( ) const

inline

Method to get descriptor number.

Returns

Descriptor number.

Definition at line 528 of file PosixDescriptor.hpp.

                                               {
                return fd_;
        }

Here is the caller graph for this function:

int ioctl ( int  request )

inline

Ioctl on the file descriptor.

Definition at line 592 of file PosixDescriptor.hpp.

                                     {
                return ::ioctl(fd_, request);
        }

Here is the caller graph for this function:

int ioctl ( int  request, void *  argp  )

inline

Ioctl on the file descriptor.

Definition at line 599 of file PosixDescriptor.hpp.

                                                 {
                return ::ioctl(fd_, request, argp);
        }

Here is the call graph for this function:

PosixDescriptor& operator= ( const PosixDescriptor &  src )

inline

Assignment operator.

The assignment operator is called to copy an existing object to another object that is already existing as well. Examples:

PosixDescriptor p1, p2;
p2 = p1;

Exceptions

runtime_error

if the ::dup() returns an error

Definition at line 569 of file PosixDescriptor.hpp.

                                                               {
                if (::dup2(src.fd_, fd_) < 0) {
                        ERROR("Bad file descriptor");
                        throw std::runtime_error("PosixDescriptor: error in operator=");
                }
                return *this;
        }

int read	(	Buffer *	b,
		size_t	size
	)

Method to read from the descriptor and fill a buffer.

Note: this method may block current thread if data is not available. The buffer is filled with the read data.

Parameters

b	Pointer to the buffer to be filled
size	Number of bytes that must be read

Returns

-1 in case of error; the number of bytes read otherwise

Definition at line 184 of file PosixDescriptor.cpp.

{
        if (b->getSize() == 0 || size > b->getSize()) {
                ERROR("Buffer size not enough!");
                return -1;
        }
        int ret = do_read(b->getBuffer(), size);
        return ret;
}

Here is the call graph for this function:

Here is the caller graph for this function:

int read	(	void *	p,
		size_t	size
	)

Method to read from the descriptor.

Note: this method may block current thread if data is not available. The buffer is filled with the read data.

Parameters

p	Pointer to the memory space to be filled
size	Number of bytes that must be read

Returns

-1 in case of error; the number of bytes read otherwise

Definition at line 203 of file PosixDescriptor.cpp.

{
        int ret = do_read(p, size);
        return ret;
}

Here is the call graph for this function:

int write	(	Buffer *	b,
		size_t	size
	)

Method to write data in a buffer to the descriptor.

Note: this method may block current thread if data cannot be written.

Parameters

b	Pointer to the buffer to be filled
size	Number of bytes that must be written

Returns

-1 in case of error; the number of bytes read otherwise

Definition at line 251 of file PosixDescriptor.cpp.

{
        if (b->getSize() == 0 || size > b->getSize()) {
                ERROR("Buffer size not enough!");
                return -1;
        }
        return do_write(reinterpret_cast<const void*> (b->getBuffer()),
            size);
}

Here is the call graph for this function:

Here is the caller graph for this function:

int write	(	const void *	p,
		size_t	size
	)

Method to write to the descriptor.

Note: this method may block current thread if data cannot be written.

Parameters

p	Pointer to the memory space containing data
size	Number of bytes that must be written

Returns

-1 in case of error; the number of bytes read otherwise

Definition at line 269 of file PosixDescriptor.cpp.

{
        return do_write(p, size);
}

Here is the call graph for this function:

int write

(

const std::string &

s

)

Method to write a string to the descriptor.

Note: this method may block current thread if data cannot be written.

Parameters

string

to be written

Returns

-1 in case of error; the number of bytes read otherwise

Definition at line 282 of file PosixDescriptor.cpp.

{
        return do_write(reinterpret_cast<const void*> (s.c_str()), s.size());
}

Here is the call graph for this function:

Friends And Related Function Documentation

friend class AsyncThread

friend

Definition at line 358 of file PosixDescriptor.hpp.

friend class Pipe

friend

Definition at line 357 of file PosixDescriptor.hpp.

Member Data Documentation

int fd_

protected

Number of the file descriptor.

This is the return value of open(), socket() or accept().

Definition at line 366 of file PosixDescriptor.hpp.

shared_queue* queue_

private

Pointer to the shared_queue for synchronization with the worker thread.

This data structure is allocated on the heap in the constructors (2 standard + 1 copy) and deallocated in the destructor.

Definition at line 336 of file PosixDescriptor.hpp.

Worker* worker_

private

Pointer to the worker that performs asynchronous operations.

The worker is allocated on the heap in the constructors (2 standard + 1 copy) and deallocated in the destructor.

Definition at line 327 of file PosixDescriptor.hpp.

bool worker_started_

private

If the worker thread has been already started.

This variable is modified in async_read() and async_write();

Definition at line 343 of file PosixDescriptor.hpp.

---

The documentation for this class was generated from the following files:

• /home/cloud/work/onposix-code/include/PosixDescriptor.hpp
• /home/cloud/work/onposix-code/src/PosixDescriptor.cpp