Class with methods to listen a specific port and, as additionnal functionality, manage multiple peers. Methods for insertion, removal and visiting peers are provided. More...

#include <gcg.h>

Inheritance diagram for gcgINETSERVICE:

Public Member Functions
	gcgINETSERVICE ()
	Constructs a valid service but still not capable of accepting connections.

virtual	~gcgINETSERVICE ()
	If processEvents() is running, signals it to stop handling processes and exit. Then calls stopListening() and frees all resources. More...

bool	listenPort (int port)
	Prepares the service to listen the desired port. If successful, the service becomes ready to accept new clients by the specified port. New connections are managed by each processing round of processEvents(). When a new connection is accepted by processEvents(), it calls eventHandler() with the new peer and the event bit GCG_EVENT_NEWCONNECTION on. More...

bool	stopListening ()
	Stops the listening, shutting down and closing the service peer. No further connections are accepted. More...

bool	insertPeer (gcgINETPEER *peer)
	Insert a new peer to the service group. The peer must be connected and is inserted with event flags checkReceive = true and checkSend = false (see flagEvents()). If correctly inserted, the next round of processing of processEvents() calls eventHandler() for the peer with the bit GCG_EVENT_INSERTED on. After insertion, the peer communication can be managed by the service group in conjunction with other peers, saving resources and optimizing responses. Normally, a peer is inserted in the virtual (callback) function eventHandler() after being accepted by a new connection event GCG_EVENT_NEWCONNECTION. After insertion, this function wakes up the processEvents() if it is blocked. More...

int	getPeerCount ()
	Gets the number of peers of the service group. More...

bool	flagEvents (gcgINETPEER *peer, bool checkReceive, bool checkSend)
	Flags which communication events are to be checked for a specific peer during a round of processing of processEvents(). If checkReceive is true, the processEvents() will check if there are available messages and, if so, will call the eventHandler() function with GCG_EVENT_RECEIVEREADY bit on. If checkSend is true, the event verification will check if the peer can send messages and, if so, will call the eventHandler() function with GCG_EVENT_SENDREADY bit on. If checkSend and checkReceive are both true, both events are checked in each round and, if detected, are reported to processEvents() with respective bits flagged. If both parameters are false, then event processor just watchs for errors or disconnection. Note that processEvents() calls eventHandler() for other events like insertions, new connections, visitations and removals. More...

bool	postRemove (gcgINETPEER *peer)
	Flags the peer to be removed in the next round of processing of processEvents(). After the peer flag is changed, this function wakes up the processEvents() if it is blocked. It causes processEvents() to call eventHandler with a GCG_EVENT_REMOVED flagged for the peer. The eventHandler() must delete/release the peer since processEvents() only removes it from the service group. More...

bool	postRemoveAll ()
	Flags all the peers of the service group to be removed in the next round of processing of processEvents(). This function wakes up the processEvents() if it is blocked. After removals, the service keeps accepting new connections. It causes processEvents() to call eventHandler with a GCG_EVENT_REMOVED flagged for all the peers grouped in the service. The eventHandler() must delete/release the each peer since processEvents() only removes it from the service group. More...

bool	postVisit (gcgINETPEER *peer)
	Flags the peer to be visited in the next round of processing of processEvents(). Visiting is a strategy for programmers to apply specific tasks to a peer. After the peer flag is changed, this function wakes up the processEvents() if it is blocked. More...

bool	postVisitAll ()
	Flags all the peers of the service group to be visited in the next round of processing of processEvents(). Visiting is a strategy for programmers to apply specific tasks to peers. This function wakes up the processEvents() if it is blocked. More...

bool	postExit ()
	Flags the processEvents() to process all remaining events, release the thread pool used to execute several instances of eventHandler(), and exit safely. This function wakes up the processEvents() if it is blocked. More...

bool	processEvents (unsigned int numThreads=gcgGetNumberOfProcessors())
	The method processEvents() is responsible for new connections accepted for the listening port, and send/receive events for peer members. Additionaly, this method informs when a peer is inserted or removed. All these events are informed by calls to a pure virtual method eventHandler() that must be defined by the programmer. Method processEvents() processes events in rounds of some amount of time. To specify this amount of time for waiting events use the setTimeout() method. It blocks the calling process until a postExit() call flags it to finish event processing. The events are treated in parallel using a thread pool where multiple calls to eventHandler() may be running. Thus, the programmer must be careful of using non-local variables or resources inside eventHandler(). The number of threads is specified by a parameter of the processEvents() call. All methods of this class are thread safe. Only one instance of processEvents is allowed to run at a time. If no processEvents() is running, new connections and peer events are not treated. All peers must be inserted by calling insertPeer(), even the connected peers from the listening port. In a round of processing of processEvents(), only one event is processed at a time for a given peer, even thought multiple peers might be being processed in parallel. Method processEvents() works by multiplexing input/output of multiple peers using the select() function with sockets. This is much more efficient and scalable than using a exclusive thread for each peer. To extend funcionality for users, a peer visitation mechanism is also supported. More...

bool	setTimeout (int timeoutUsec)
	The method processEvents() processes events in rounds of some amount of time. To specify this amount of time for waiting events use the setTimeout() method. The default timeout is 100 miliseconds. It is a thread safe function. More...

virtual void	eventHandler (int events, gcgINETPEER *peer)=0
	Pure virtual method to be defined by the user in a specialized class for a service. This methods is called by processEvents() for every event occurred. When a GCG_EVENT_REMOVED event is flagged, the eventHandler() must release the resources of the peer since processEvents() only removes the peer from the service group. Method processEvents() use a thread pool (see gcgTHREADPOOL), to call multiple instances of eventHandler at a time. It is important that eventHandler() be fast and thread safe, with careful access to non-local variables. More...

Public Member Functions inherited from gcgCLASS
void *	operator new (size_t size)
	Defines a new operator to be used by instatiations of GCGlib classes instead the global one. More...

void *	operator new (size_t size, const std::nothrow_t &) throw ()
	Defines a new operator to be used by instantiations of GCGlib classes instead the global one. Returns a NULL pointer instead of throwing an exception if an error occurs. More...

void *	operator new[] (size_t size)
	Defines a new operator to be used by GCGlib array allocations instead the global one. More...

void *	operator new[] (size_t size, const std::nothrow_t &) throw ()
	Defines a new operator to be used by vector allocations instead the global one. More...

void	operator delete (void *p)
	Defines a delete operator to free instances of GCGlib classes instead the global one. It is designed to match the new operator. More...

void	operator delete (void *p, const std::nothrow_t &) throw ()
	Defines a delete operator to free instances of GCGlib classes instead the global one. It is designed to match the new operator. More...

void	operator delete[] (void *p)
	Defines a delete operator to free instances of arrays for GCGlib classes instead the global one. It is designed to match the new[] operator. More...

void	operator delete[] (void *p, const std::nothrow_t &) throw ()
	Defines a delete operator to free instances of arrays for GCGlib classes instead the global one. It is designed to match the new[] operator. More...

Public Attributes
bool	isListening
	True if the service is listening a port.

void *	handle
	Internal handle of this service.

Detailed Description

Class with methods to listen a specific port and, as additionnal functionality, manage multiple peers. Methods for insertion, removal and visiting peers are provided.

The method processEvents() is responsible for new connections accepted for the listening port, and send/receive events for peer members. Additionaly, this method informs when a peer is inserted or removed. All these events are informed by calls to a pure virtual method eventHandler() that must be defined by the programmer. Method processEvents() processes events in rounds of some amount of time. To specify this amount of time for waiting events use the setTimeout() method. It blocks the calling process until a postExit() call flags it to finish event processing. The events are treated in parallel using a thread pool where multiple calls to eventHandler() may be running. Thus, the programmer must be careful of using non-local variables or resources inside eventHandler(). The number of threads is specified by a parameter of the processEvents() call. All methods of this class are thread safe. Only one instance of processEvents is allowed to run at a time. If no processEvents() is running, new connections and peer events are not treated. All peers must be inserted by calling insertPeer(), even the connected peers accepted from the listening port. In a round of processing of processEvents(), only one event is processed at a time for a given peer, even thought multiple peers might be being processed in parallel. Method processEvents() works by multiplexing input/output of multiple peers using the select() function with sockets. This is much more efficient and scalable than using a exclusive thread for each peer.

Since: 0.01.6

Constructor & Destructor Documentation

◆ ~gcgINETSERVICE()

virtual gcgINETSERVICE::~gcgINETSERVICE ( )

virtual

If processEvents() is running, signals it to stop handling processes and exit. Then calls stopListening() and frees all resources.

See also: processEvents()

Member Function Documentation

◆ eventHandler()

virtual void gcgINETSERVICE::eventHandler	(	int	events,
		gcgINETPEER *	peer
	)

pure virtual

Pure virtual method to be defined by the user in a specialized class for a service. This methods is called by processEvents() for every event occurred. When a GCG_EVENT_REMOVED event is flagged, the eventHandler() must release the resources of the peer since processEvents() only removes the peer from the service group. Method processEvents() use a thread pool (see gcgTHREADPOOL), to call multiple instances of eventHandler at a time. It is important that eventHandler() be fast and thread safe, with careful access to non-local variables.

Parameters

[in]	events	a 32bit mask formed by a combination of bitwise or of event codes. Ex. GCG_EVENT_INSERTED, GCG_EVENT_REMOVED, GCG_EVENT_VISIT, GCG_EVENT_NEWCONNECTION, GCG_EVENT_RECEIVEREADY and GCG_EVENT_SENDREADY.
[in]	peer	peer for which the events must be processed.

See also: processEvents(); setTimeout()

◆ flagEvents()

bool gcgINETSERVICE::flagEvents	(	gcgINETPEER *	peer,
		bool	checkReceive,
		bool	checkSend
	)

Flags which communication events are to be checked for a specific peer during a round of processing of processEvents(). If checkReceive is true, the processEvents() will check if there are available messages and, if so, will call the eventHandler() function with GCG_EVENT_RECEIVEREADY bit on. If checkSend is true, the event verification will check if the peer can send messages and, if so, will call the eventHandler() function with GCG_EVENT_SENDREADY bit on. If checkSend and checkReceive are both true, both events are checked in each round and, if detected, are reported to processEvents() with respective bits flagged. If both parameters are false, then event processor just watchs for errors or disconnection. Note that processEvents() calls eventHandler() for other events like insertions, new connections, visitations and removals.

Parameters

[in]	peer	peer to be checked using the parameters. The peer must have been included in the service group.
[in]	checkReceive	pass true if processEvents() should check if there are incoming messages.
[in]	checkSend	pass true if processEvents() should check if the output buffer is not completely full. Even if the peer is ready to send, it does not imply that calling send() will not block. This also depends on the size of the message.

Returns: true if the flags are updated for the peer. If it returns false, check GCG_REPORT_MESSAGE(gcgGetReport()) for knowing the problem.

See also: insertPeer(); setTimeout(); getPeerCount(); postRemove(); postRemoveAll(); processEvents(); eventHandler()

◆ getPeerCount()

int gcgINETSERVICE::getPeerCount ( )

Gets the number of peers of the service group.

Returns: If successful, returns the current number of peers grouped into the service. If it returns -1, check GCG_REPORT_MESSAGE(gcgGetReport()) for knowing the problem.

See also: insertPeer(); postRemove(); postRemoveAll(); processEvents(); eventHandler()

◆ insertPeer()

bool gcgINETSERVICE::insertPeer ( gcgINETPEER * peer )

Insert a new peer to the service group. The peer must be connected and is inserted with event flags checkReceive = true and checkSend = false (see flagEvents()). If correctly inserted, the next round of processing of processEvents() calls eventHandler() for the peer with the bit GCG_EVENT_INSERTED on. After insertion, the peer communication can be managed by the service group in conjunction with other peers, saving resources and optimizing responses. Normally, a peer is inserted in the virtual (callback) function eventHandler() after being accepted by a new connection event GCG_EVENT_NEWCONNECTION. After insertion, this function wakes up the processEvents() if it is blocked.

Parameters

[in] peer new peer to be inserted to the service group. If succesfully inserted, the original peer must not be deleted. It must be deleted by processEvents() and eventHandler() upon removal events (see postRemove() and postRemoveAll()).

Returns: true if the peer is inserted . If it returns false, check GCG_REPORT_MESSAGE(gcgGetReport()) for knowing the problem.

See also: getPeerCount(); flagEvents(); postRemove(); postRemoveAll(); processEvents(); eventHandler()

◆ listenPort()

bool gcgINETSERVICE::listenPort ( int port )

Prepares the service to listen the desired port. If successful, the service becomes ready to accept new clients by the specified port. New connections are managed by each processing round of processEvents(). When a new connection is accepted by processEvents(), it calls eventHandler() with the new peer and the event bit GCG_EVENT_NEWCONNECTION on.

Parameters

[in] port port to be used by clients for connecting to this service.

Returns: true if the service is ready to accept new connections. If it returns false, check GCG_REPORT_MESSAGE(gcgGetReport()) for knowing the problem.

See also: stopListening(); processEvents()

◆ postExit()

bool gcgINETSERVICE::postExit ( )

Flags the processEvents() to process all remaining events, release the thread pool used to execute several instances of eventHandler(), and exit safely. This function wakes up the processEvents() if it is blocked.

Returns: true if the peer is flagged to be removed. If it returns false, check GCG_REPORT_MESSAGE(gcgGetReport()) for knowing the problem.

See also: postRemoveAll(); processEvents(); eventHandler()

◆ postRemove()

bool gcgINETSERVICE::postRemove ( gcgINETPEER * peer )

Flags the peer to be removed in the next round of processing of processEvents(). After the peer flag is changed, this function wakes up the processEvents() if it is blocked. It causes processEvents() to call eventHandler with a GCG_EVENT_REMOVED flagged for the peer. The eventHandler() must delete/release the peer since processEvents() only removes it from the service group.

Parameters

[in] peer peer to be removed. The peer must have been included in the service group or a warning is issued.

Returns: true if the peer is flagged to be removed. If it returns false, check GCG_REPORT_MESSAGE(gcgGetReport()) for knowing the problem.

See also: postRemoveAll(); processEvents(); eventHandler()

◆ postRemoveAll()

bool gcgINETSERVICE::postRemoveAll ( )

Flags all the peers of the service group to be removed in the next round of processing of processEvents(). This function wakes up the processEvents() if it is blocked. After removals, the service keeps accepting new connections. It causes processEvents() to call eventHandler with a GCG_EVENT_REMOVED flagged for all the peers grouped in the service. The eventHandler() must delete/release the each peer since processEvents() only removes it from the service group.

Returns: true if the peers (if any) were flagged to be removed. If it returns false, check GCG_REPORT_MESSAGE(gcgGetReport()) for knowing the problem.

See also: postRemove(); processEvents(); eventHandler()

◆ postVisit()

bool gcgINETSERVICE::postVisit ( gcgINETPEER * peer )

Flags the peer to be visited in the next round of processing of processEvents(). Visiting is a strategy for programmers to apply specific tasks to a peer. After the peer flag is changed, this function wakes up the processEvents() if it is blocked.

Parameters

[in] peer peer to be visited. The peer must have been included in the service group or a warning is issued.

Returns: true if the peer is flagged to be visited. If it returns false, check GCG_REPORT_MESSAGE(gcgGetReport()) for knowing the problem.

See also: postVisitAll(); processEvents(); eventHandler()

◆ postVisitAll()

bool gcgINETSERVICE::postVisitAll ( )

Flags all the peers of the service group to be visited in the next round of processing of processEvents(). Visiting is a strategy for programmers to apply specific tasks to peers. This function wakes up the processEvents() if it is blocked.

Returns: true if the peers (if any) were flagged to be visited. If it returns false, check GCG_REPORT_MESSAGE(gcgGetReport()) for knowing the problem.

See also: postVisit(); processEvents(); eventHandler()

◆ processEvents()

bool gcgINETSERVICE::processEvents ( unsigned int numThreads = gcgGetNumberOfProcessors() )

The method processEvents() is responsible for new connections accepted for the listening port, and send/receive events for peer members. Additionaly, this method informs when a peer is inserted or removed. All these events are informed by calls to a pure virtual method eventHandler() that must be defined by the programmer. Method processEvents() processes events in rounds of some amount of time. To specify this amount of time for waiting events use the setTimeout() method. It blocks the calling process until a postExit() call flags it to finish event processing. The events are treated in parallel using a thread pool where multiple calls to eventHandler() may be running. Thus, the programmer must be careful of using non-local variables or resources inside eventHandler(). The number of threads is specified by a parameter of the processEvents() call. All methods of this class are thread safe. Only one instance of processEvents is allowed to run at a time. If no processEvents() is running, new connections and peer events are not treated. All peers must be inserted by calling insertPeer(), even the connected peers from the listening port. In a round of processing of processEvents(), only one event is processed at a time for a given peer, even thought multiple peers might be being processed in parallel. Method processEvents() works by multiplexing input/output of multiple peers using the select() function with sockets. This is much more efficient and scalable than using a exclusive thread for each peer. To extend funcionality for users, a peer visitation mechanism is also supported.

Parameters

[in] numThreads number of thread to be created in a thread pool. When an event occurs, processEvents() assigns a job to a free thread to execute an instance of eventHandler(). If no thread is available, processEvents() blocks until a job finish to execute eventHandler(). Thus, It is important that eventHandler() be fast and thread safe, with careful access to non-local variables. Tipically, the number of threads should match the number of processors of the machine. Use gcgGetNumberOfProcessors() for this purpose.

Returns: true if exits normally, without any errors. If it returns false, check GCG_REPORT_MESSAGE(gcgGetReport()) for knowing the problem.

See also: flagEvents(); postRemove(); postRemoveAll(); postVisit(); postVisitAll(); eventHandler(); setTimeout(); gcgGetNumberOfProcessors()

◆ setTimeout()

bool gcgINETSERVICE::setTimeout ( int timeoutUsec )

The method processEvents() processes events in rounds of some amount of time. To specify this amount of time for waiting events use the setTimeout() method. The default timeout is 100 miliseconds. It is a thread safe function.

Parameters

[in] timeoutUsec timeout to be used in processEvents() in microseconds.

Returns: true if the timeout was updated. If it returns false, check GCG_REPORT_MESSAGE(gcgGetReport()) for knowing the problem.

See also: processEvents(); eventHandler()

◆ stopListening()

bool gcgINETSERVICE::stopListening ( )

Stops the listening, shutting down and closing the service peer. No further connections are accepted.

Returns: true if the service was correctly stoped. If it returns false, check GCG_REPORT_MESSAGE(gcgGetReport()) for knowing the problem.

See also: listenPort(); processEvents()

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

M:/Documentos/Projetos/Projetos/GCGlib/src/gcg.h

Public Member Functions

Public Attributes

Detailed Description

Constructor & Destructor Documentation

◆ ~gcgINETSERVICE()

Member Function Documentation

◆ eventHandler()

◆ flagEvents()

◆ getPeerCount()

◆ insertPeer()

◆ listenPort()

◆ postExit()

◆ postRemove()

◆ postRemoveAll()

◆ postVisit()

◆ postVisitAll()

◆ processEvents()

◆ setTimeout()

◆ stopListening()