SoDisp Struct Reference

Detailed Description

The SoDisp dispatches any socket connection that contains data by calling the SoDispCon::execute member function in a SoDispCon object.

This class contains the socket dispatcher loop which waits for data on all registered socket connections. A socket connection is stored in a SoDispCon object, and the dispatcher object dispatches the socket connection by calling SoDispCon::execute.

The SoDisp class is platform dependent and may be implemented differently for various operating systems. Keep registered connection objects alive until they have been deactivated and removed. Registration transfers no allocation ownership. Hold the dispatcher mutex when changing connection registration or event state from another thread. The "generic SoDisp" is using "socket select" and waits in a loop for the next active socket connection.

#include <SoDisp.h>

Public Member Functions
	SoDisp (ThreadMutex *mutex)
	The constructor. More...
void	mutexSet ()
	Lock the dispatcher thread. More...
void	mutexRelease ()
	Release the mutex currently owned by this thread. More...
ThreadMutex *	getMutex ()
void	addConnection (SoDispCon *con)
	Register a connection without enabling events. More...
void	activateRec (SoDispCon *con)
	Enable receive events. More...
void	deactivateRec (SoDispCon *con)
	Disable receive events without closing or unregistering the connection. More...
void	activateSend (SoDispCon *con)
	Enable send-ready events. More...
void	deactivateSend (SoDispCon *con)
	Disable send-ready events without closing or unregistering the connection. More...
void	removeConnection (SoDispCon *con)
	Unregister a connection without closing or freeing it. More...
void	setExit ()
	Request that the current run loop exits after it regains control. More...
void	run (S32 timeout=-1)
	Run the generic socket dispatcher loop. More...

Constructor & Destructor Documentation

SoDisp()

SoDisp::SoDisp

(

ThreadMutex *

mutex

)

The constructor.

Parameters

mutex

Borrowed initialized mutex protecting the server, valid throughout dispatcher use. Use a real mutex for multithreaded builds; NULL is only suitable for ports/configurations supporting no mutex.

Member Function Documentation

activateRec()

void SoDisp::activateRec

(

SoDispCon *

con

)

Enable receive events.

Parameters

[in,out]

con

Registered connection whose receive events are currently inactive. Callback storage must remain valid while enabled.

activateSend()

void SoDisp::activateSend

(

SoDispCon *

con

)

Enable send-ready events.

Parameters

[in,out]

con

Registered valid connection with a send callback and send events currently inactive. No operation in NO_ASYNCH_RESP builds.

addConnection()

void SoDisp::addConnection

(

SoDispCon *

con

)

Register a connection without enabling events.

Parameters

[in,out]

con

Borrowed initialized connection associated with this dispatcher, not already registered. Call activateRec/activateSend next.

deactivateRec()

void SoDisp::deactivateRec

(

SoDispCon *

con

)

Disable receive events without closing or unregistering the connection.

Parameters

[in,out]

con

Registered connection with receive events active.

deactivateSend()

void SoDisp::deactivateSend

(

SoDispCon *

con

)

Disable send-ready events without closing or unregistering the connection.

Parameters

[in,out]

con

Connection with send events active. No operation in NO_ASYNCH_RESP builds.

getMutex()

ThreadMutex * SoDisp::getMutex

(

)

Returns

Borrowed configured mutex, possibly NULL in a no-mutex setup. Does not acquire it.

mutexRelease()

void SoDisp::mutexRelease

(

)

Release the mutex currently owned by this thread.

Recursive acquisition/release is not portable across ThreadLib ports. Releases the mutex set with function SoDisp::mutexSet.

mutexSet()

void SoDisp::mutexSet

(

)

Lock the dispatcher thread.

This function protects the web-server with a mutex and makes it possible for threads to call functions in the web-server. One mutexSet call must be followed by one SoDisp::mutexRelease call.

removeConnection()

void SoDisp::removeConnection

(

SoDispCon *

con

)

Unregister a connection without closing or freeing it.

Parameters

[in,out]

con

Registered connection. Deactivate both receive and send events before removal; repeated removal is incorrect usage.

run()

void SoDisp::run

(

S32

timeout = -1

)

Run the generic socket dispatcher loop.

Parameters

[in]

timeout

Per-wait timeout in milliseconds. Negative values (default -1) keep dispatching until setExit. Nonnegative values allow return after a wait without events, but repeated activity can extend the call indefinitely. Zero polls available events when sockets exist. With no monitored sockets, the generic port sleeps for its internal poll delay even when timeout is zero. This is not a total time budget. Call from one dispatcher thread, without already owning its mutex. The loop acquires the mutex for callbacks and releases it while waiting. This void interface reports no select error; scheduling behavior differs in non-generic dispatcher implementations.

setExit()

void SoDisp::setExit

(

)

Request that the current run loop exits after it regains control.

Does not interrupt a running callback or necessarily wake a socket wait. The generic dispatcher clears this flag when run starts, so setting it before run does not cancel that future call.