# Poco::Net

# class SocketProactor final

Library: Net
Package: Sockets
Header: Poco/Net/SocketProactor.h

## Description

This class implements the proactor pattern. It may also contain a simple work executor (enabled by default), which executes submitted workload.

## Inheritance

Direct Base Classes: Poco::Runnable

All Base Classes: Poco::Runnable

## Member Summary

Member Functions: addReceive, addReceiveFrom, addSend, addSendTo, addSocket, addWork, getTimeout, has, hasSocketHandlers, ioCompletionInProgress, isRunning, operator =, permanentWork, poll, removePermanentWork, removeScheduledWork, removeSocket, removeWork, run, runOne, scheduledWork, setTimeout, stop, updateSocket, wait, wakeUp

Inherited Functions: run

## Types Aliases

### Buffer

using Buffer = std::vector < std::uint8_t >;

### Callback

using Callback = std::function < void (const std::error_code & failure, int bytesReceived)>;

### Work

using Work = std::function < void ()>;

## Constructors

### SocketProactor

explicit SocketProactor(
bool worker = true
);

Creates the SocketProactor.

### SocketProactor

SocketProactor(
const SocketProactor & param494
) = delete;

### SocketProactor

SocketProactor(
SocketProactor && param495
) = delete;

### SocketProactor

explicit SocketProactor(
const Poco::Timespan & timeout,
bool worker = true
);

Creates the SocketProactor, using the given timeout.

## Destructor

### ~SocketProactor

~SocketProactor() override;

Destroys the SocketProactor.

## Member Functions

### addReceive

void addReceive(
Socket sock,
Buffer & buf,
Callback && onCompletion
);

Adds the stream socket and the completion handler to the I/O receive queue.

### addReceiveFrom

void addReceiveFrom(
Socket sock,
Buffer & buf,
SocketAddress & addr,
Callback && onCompletion
);

Adds the datagram socket and the completion handler to the I/O receive queue.

### addSend

void addSend(
Socket sock,
Buffer * pMessage,
SocketAddress * pAddr,
Callback && onCompletion,
bool own = false
);

Adds the socket and the completion handler to the I/O send queue. For stream socket, pAddr can be nullptr. If `own` is true, message and address are deleted after the I/O completion.

### addSend

void addSend(
Socket sock,
const Buffer & message,
Callback && onCompletion
);

Adds the stream socket and the completion handler to the I/O send queue.

### addSend

void addSend(
Socket sock,
Buffer && message,
Callback && onCompletion
);

Adds the stream socket and the completion handler to the I/O send queue.

### addSendTo

void addSendTo(
Socket sock,
const Buffer & message,
const SocketAddress & addr,
Callback && onCompletion
);

Adds the datagram socket and the completion handler to the I/O send queue.

### addSendTo

void addSendTo(
Socket sock,
Buffer && message,
const SocketAddress && addr,
Callback && onCompletion
);

Adds the datagram socket and the completion handler to the I/O send queue.

### addSocket

void addSocket(
const Socket & sock,
int mode
);

Adds the socket to the poll set.

### addWork

void addWork(
const Work & ch,
Timestamp::TimeDiff ms = PERMANENT_COMPLETION_HANDLER
);

Adds work to be executed after the next poll() completion. Function will be called until the specified expiration, which defaults to immediately, ie. expiration after the first invocation.

### addWork

void addWork(
Work && ch,
Timestamp::TimeDiff ms = PERMANENT_COMPLETION_HANDLER,
int pos = - 1
);

Adds work to be executed after the next poll() completion. Function will be called until the specified expiration, which defaults to immediately, ie. expiration after the first invocation.

### getTimeout

Poco::Timespan getTimeout() const;

Returns the timeout.

### has

bool has(
const Socket & sock
) const;

Returns true if socket is registered with this proactor.

### hasSocketHandlers

bool hasSocketHandlers() const;

Returns true if proactor had at least one I/O completion handler.

### ioCompletionInProgress

bool ioCompletionInProgress() const;

Returns true if there are not executed handlers from last IO.

### isRunning

bool isRunning() const;

Returns true if this proactor is running

### operator =

SocketProactor & operator = (
const SocketProactor & param496
) = delete;

### operator =

SocketProactor & operator = (
SocketProactor && param497
) = delete;

### permanentWork

int permanentWork();

Returns the number of permanent functions.

### poll

int poll(
int * pHandled = nullptr
);

Polls all registered sockets and calls their respective handlers. If pHandled is not null, after the call it contains the total number of read/write/error socket handlers called. Returns the number of completion handlers invoked.

### removePermanentWork

int removePermanentWork(
int count = - 1
);

Removes the count permanent functions from the front of the schedule queue. Default is removal of all functions.

### removeScheduledWork

int removeScheduledWork(
int count = - 1
);

Removes the count scheduled functions from the front of the schedule queue. Default is removal of all scheduled functions.

### removeSocket

void removeSocket(
const Socket & sock
);

Removes the socket from the poll set.

### removeWork

void removeWork();

Removes all scheduled work.

### run

void run() override;

Runs the SocketProactor. The reactor will run until stop() is called (in a separate thread).

See also: Poco::Runnable::run()

### runOne

int runOne();

Runs one handler, scheduled or permanent. If there are no available handlers, it blocks until the first handler is encountered and executed. Returns 1 on successful handler invocation, 0 on exception.

### scheduledWork

int scheduledWork();

Returns the number of scheduled functions.

### setTimeout

void setTimeout(
const Poco::Timespan & timeout
);

Sets the timeout.

If no other event occurs for the given timeout interval, a timeout event is sent to all event listeners.

The default timeout is 250 milliseconds;

The timeout is passed to the Socket::select() method.

### stop

void stop();

Stops the SocketProactor.

The proactor will be stopped when the next event (including a timeout event) occurs.

### updateSocket

void updateSocket(
const Socket & sock,
int mode
);

Updates the socket mode in the poll set.

### wait

void wait();

Blocks and waits for the scheduled I/O completion handlers loop to end.

### wakeUp

void wakeUp();

Wakes up idle reactor.

## Variables

### PERMANENT_COMPLETION_HANDLER

static const Timestamp::TimeDiff PERMANENT_COMPLETION_HANDLER;

### POLL_ERROR

static const int POLL_ERROR = PollSet::POLL_ERROR;

### POLL_READ

static const int POLL_READ = PollSet::POLL_READ;

### POLL_WRITE

static const int POLL_WRITE = PollSet::POLL_WRITE;