SoDisp.h File Reference

#include <HttpCfg.h>
#include <ThreadLib.h>

Include dependency graph for SoDisp.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

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

Macros
#define	SoDisp_getMutex(o)   ((o) ? ((o)->mutex) : 0)
#define	SoDisp_mutexSet(o)   ThreadMutex_set((o)->mutex)
	Acquire the configured mutex; do not acquire recursively. More...
#define	SoDisp_mutexRelease(o)   ThreadMutex_release((o)->mutex)
	Release the configured mutex owned by this thread. More...
#define	SoDisp_setExit(o)   (o)->doExit=TRUE

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

Functions
BA_API void	SoDisp_constructor (SoDisp *o, ThreadMutex *mutex)
	The constructor. More...
BA_API void	SoDisp_addConnection (SoDisp *o, struct SoDispCon *con)
	Register a connection without enabling events. More...
BA_API void	SoDisp_activateRec (SoDisp *o, struct SoDispCon *con)
	Enable receive events. More...
BA_API void	SoDisp_deactivateRec (SoDisp *o, struct SoDispCon *con)
	Disable receive events without closing or unregistering the connection. More...
BA_API void	SoDisp_activateSend (SoDisp *o, struct SoDispCon *con)
	Enable send-ready events. More...
BA_API void	SoDisp_deactivateSend (SoDisp *o, struct SoDispCon *con)
	Disable send-ready events without closing or unregistering the connection. More...
BA_API void	SoDisp_removeConnection (SoDisp *o, struct SoDispCon *con)
	Unregister a connection without closing or freeing it. More...
BA_API void	SoDisp_run (SoDisp *o, S32 timeout)
	Run the generic socket dispatcher loop. More...

Macro Definition Documentation

SoDisp_getMutex

#define SoDisp_getMutex

(

o

)

((o) ? ((o)->mutex) : 0)

Parameters

[in]

o

Dispatcher, or NULL.

Returns

Borrowed configured mutex, or NULL for no dispatcher/mutex.

SoDisp_mutexRelease

#define SoDisp_mutexRelease

(

o

)

ThreadMutex_release((o)->mutex)

Release the configured mutex owned by this thread.

Parameters

[in,out]

o

Initialized dispatcher.

SoDisp_mutexSet

#define SoDisp_mutexSet

(

o

)

ThreadMutex_set((o)->mutex)

Acquire the configured mutex; do not acquire recursively.

Parameters

[in,out]

o

Initialized dispatcher with a usable mutex.

SoDisp_setExit

#define SoDisp_setExit

(

o

)

(o)->doExit=TRUE

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.

Parameters

[in,out]

o

Dispatcher whose active run loop should exit.

Typedef Documentation

SoDisp

typedef struct SoDisp SoDisp

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.

Function Documentation

SoDisp_activateRec()

BA_API void SoDisp_activateRec	(	SoDisp *	o,
		struct SoDispCon *	con
	)

Enable receive events.

Parameters

[in,out]	con	Registered connection whose receive events are currently inactive. Callback storage must remain valid while enabled.
[in,out]	o	Caller-owned dispatcher instance.

SoDisp_activateSend()

BA_API void SoDisp_activateSend	(	SoDisp *	o,
		struct 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.
[in,out]	o	Caller-owned dispatcher instance.

SoDisp_addConnection()

BA_API void SoDisp_addConnection	(	SoDisp *	o,
		struct 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.
[in,out]	o	Caller-owned dispatcher instance.

SoDisp_constructor()

BA_API void SoDisp_constructor	(	SoDisp *	o,
		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.
[in,out]	o	Caller-owned dispatcher instance.

SoDisp_deactivateRec()

BA_API void SoDisp_deactivateRec	(	SoDisp *	o,
		struct SoDispCon *	con
	)

Disable receive events without closing or unregistering the connection.

Parameters

[in,out]	con	Registered connection with receive events active.
[in,out]	o	Caller-owned dispatcher instance.

SoDisp_deactivateSend()

BA_API void SoDisp_deactivateSend	(	SoDisp *	o,
		struct 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.
[in,out]	o	Caller-owned dispatcher instance.

SoDisp_removeConnection()

BA_API void SoDisp_removeConnection	(	SoDisp *	o,
		struct 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.
[in,out]	o	Caller-owned dispatcher instance.

SoDisp_run()

BA_API void SoDisp_run	(	SoDisp *	o,
		S32	timeout
	)

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.
[in,out]	o	Caller-owned dispatcher instance.