ONPOSIX  2.0
 All Classes Namespaces Files Functions Variables Enumerator Friends Macros Pages
PosixDescriptor Class Reference

Abstraction of a POSIX descriptor. More...

#include <PosixDescriptor.hpp>

Inheritance diagram for PosixDescriptor:
Inheritance graph

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.
PosixDescriptoroperator= (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

Workerworker_
 Pointer to the worker that performs asynchronous operations.
shared_queuequeue_
 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
fdFile 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:

PosixDesscriptor p3 (p1);

It allocates queue_ and worker_.

Exceptions
runtime_errorif 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
handlerFunction 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.
bPointer to the Buffer to be provided to the handler function as argument
sizeNumber of bytes to be read

Definition at line 413 of file PosixDescriptor.hpp.

{
DEBUG("async_read() called!");
}
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
handlerFunction 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.
bPointer to be provided to the handler function as argument
sizeNumber of bytes to be read

Definition at line 437 of file PosixDescriptor.hpp.

{
DEBUG("async_read() called!");
}
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
handlerFunction 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.
bPointer to the Buffer to be provided to the handler function as argument
sizeNumber of bytes to be written.

Definition at line 462 of file PosixDescriptor.hpp.

{
}
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
handlerFunction 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.
bPointer to be provided to the handler function as argument
sizeNumber of bytes to be written

Definition at line 485 of file PosixDescriptor.hpp.

{
}
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.

{
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
bufferPointer to the buffer where read bytes must be stored
sizeNumber of bytes to be read
Exceptions
runtime_errorif 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
bufferPointer to the buffer containing bytes to be written
sizeNumber of bytes to be written
Exceptions
runtime_errorif 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:

p2 = p1;
Exceptions
runtime_errorif 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
bPointer to the buffer to be filled
sizeNumber 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
pPointer to the memory space to be filled
sizeNumber 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
bPointer to the buffer to be filled
sizeNumber 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
pPointer to the memory space containing data
sizeNumber 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
stringto 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: