Base class for implementing an SCP pool with one thread listening for incoming TCP/IP connections and spawning a number of SCP worker threads that handle the incoming DICOM association on that connection. More...

Inheritance diagram for DcmBaseSCPPool:

Classes
class	DcmBaseSCPWorker
	Abstract base class that handles forwarding the configuration and T_ASC_Association to the actual worker class for each worker thread. More...

Public Member Functions
virtual	~DcmBaseSCPPool ()
	Virtual destructor, frees internal memory.
virtual void	setMaxThreads (const Uint16 maxWorkers)
	Set the number of maximum permitted connections, i.e. threads/workers.
virtual Uint16	getMaxThreads ()
	Get number of maximum permitted connections, i.e. threads/workers.
virtual size_t	numThreads (const OFBool onlyBusy)
	Get number of currently active connections.
virtual OFCondition	listen ()
	Listen for incoming association requests.
virtual DcmSCPConfig &	getConfig ()
	Return handle to the SCP configuration that is used to configure how to handle incoming associations.
virtual void	stopAfterCurrentAssociations ()
	Request the pool to stop listening for incoming requests.

Protected Member Functions
	DcmBaseSCPPool ()
	Constructor.
virtual DcmBaseSCPWorker *	createSCPWorker ()=0
	Create SCP worker.
OFCondition	runAssociation (T_ASC_Association *assoc, const DcmSharedSCPConfig &sharedConfig)
	Try to find worker to run the association.
virtual void	dropAndDestroyAssociation (T_ASC_Association *assoc)
	Drops association and clears internal structures to free memory.
void	rejectAssociation (T_ASC_Association *assoc, const T_ASC_RejectParametersReason &reason)
	Reject association using the given reason, e.g. because maximum number of connections is currently already served.
void	notifyWorkerDone (DcmBaseSCPWorker *thread, OFCondition result)
	Used by thread to tell pool it has terminated.
virtual OFCondition	initializeNetwork (T_ASC_Network **network)
	Initialize network, i.e.

Private Types
enum	runmode { LISTEN , STOP , SHUTDOWN }
	Possible run modes of pool. More...

Private Member Functions
void	finishListening ()
	Set m_runMode to SHUTDOWN on return from listen function.
void	reapFinishedWorkers ()
	Join and delete all worker threads that have finished handling their association.
runmode	getRunMode ()
	Thread-safe read of the current run mode, guarded by m_criticalSection.
void	setRunMode (const runmode mode)
	Thread-safe update of the current run mode, guarded by m_criticalSection.

Private Attributes
OFMutex	m_criticalSection
	Mutex that guards the worker lists, the maximum number of workers and the run mode.
OFList< DcmBaseSCPWorker * >	m_workersBusy
	List of all workers running a connection.
OFList< DcmBaseSCPWorker * >	m_workersIdle
	List of all workers that have finished their connection and are waiting to be joined and deleted (see reapFinishedWorkers()).
DcmSCPConfig	m_cfg
	SCP configuration to be used by pool and all workers.
Uint16	m_maxWorkers
	Maximum number of workers that can exist at a time.
volatile runmode	m_runMode
	Current run mode of pool.

Detailed Description

Base class for implementing an SCP pool with one thread listening for incoming TCP/IP connections and spawning a number of SCP worker threads that handle the incoming DICOM association on that connection.

This base class is abstract.

Remarks: This class is only available if DCMTK is compiled with thread support enabled.

Member Enumeration Documentation

◆ runmode

enum DcmBaseSCPPool::runmode

private

Possible run modes of pool.

Enumerator
LISTEN	Listen for new connections.
STOP	Stop listening after the current call waiting for a connection returns.
SHUTDOWN	Shutting down worker threads.

Constructor & Destructor Documentation

◆ ~DcmBaseSCPPool()

virtual DcmBaseSCPPool::~DcmBaseSCPPool ( )

virtual

Virtual destructor, frees internal memory.

Note that the destructor blocks until listen() has returned (see stopAfterCurrentAssociations()) and all worker threads have finished their associations.

◆ DcmBaseSCPPool()

DcmBaseSCPPool::DcmBaseSCPPool ( )

protected

Constructor.

Initializes internal member variables.

Referenced by DcmBaseSCPPool::DcmBaseSCPWorker::DcmBaseSCPWorker().

Member Function Documentation

◆ createSCPWorker()

virtual DcmBaseSCPWorker * DcmBaseSCPPool::createSCPWorker ( )

protectedpure virtual

Create SCP worker.

Returns: The worker created

Implemented in DcmSCPPool< SCP, SCPPool, BaseSCPWorker >.

◆ dropAndDestroyAssociation()

virtual void DcmBaseSCPPool::dropAndDestroyAssociation ( T_ASC_Association * assoc )

protectedvirtual

Drops association and clears internal structures to free memory.

Parameters

assoc The association to free

◆ getConfig()

virtual DcmSCPConfig & DcmBaseSCPPool::getConfig ( )

virtual

Return handle to the SCP configuration that is used to configure how to handle incoming associations.

For the pool, e.g. by providing settings for TCP connection timeout, and for the workers, e.g. by configuration presentation contexts and the like.

Returns: The SCP configuration(s).

◆ getMaxThreads()

virtual Uint16 DcmBaseSCPPool::getMaxThreads ( )

virtual

Get number of maximum permitted connections, i.e. threads/workers.

Returns: Number of threads permitted to exist within pool.

◆ getRunMode()

runmode DcmBaseSCPPool::getRunMode ( )

private

Thread-safe read of the current run mode, guarded by m_criticalSection.

Returns: the pool's current run mode.

◆ initializeNetwork()

virtual OFCondition DcmBaseSCPPool::initializeNetwork ( T_ASC_Network ** network )

protectedvirtual

Initialize network, i.e.

create an instance of T_ASC_Network and set transport layer if it is enabled.

Parameters

network The T_ASC_Network pointer to create the instance

Returns: EC_Normal if there were no errors during initialization.

◆ listen()

virtual OFCondition DcmBaseSCPPool::listen ( )

virtual

Listen for incoming association requests.

For each incoming request, a new worker thread is started if the number of maximum threads is not reached yet, otherwise the request is refused ("local limit exceeded"). Errors while handling a single connection request (e.g. temporary resource shortage when creating a worker thread) lead to a refusal of that request ("temporary congestion") but do not stop the server. The method only returns after stopAfterCurrentAssociations() has been called (or if network initialization failed). Note that with the default blocking connection mode a stop request only takes effect when the next connection request arrives; use non-blocking mode (see DcmSCPConfig::setConnectionBlockingMode()) together with a connection timeout for a pool that should be stoppable at any time.

Returns: The error code from network initialization if that failed, EC_Normal otherwise.

◆ notifyWorkerDone()

void DcmBaseSCPPool::notifyWorkerDone	(	DcmBaseSCPWorker *	thread,
		OFCondition	result )

protected

Used by thread to tell pool it has terminated.

Parameters

thread	The thread that is calling this function and is about to exit.
result	The final result of the thread.

◆ numThreads()

virtual size_t DcmBaseSCPPool::numThreads ( const OFBool onlyBusy )

virtual

Get number of currently active connections.

Parameters

onlyBusy Return only number of those workers that are busy with a connection and not idle, if OFTrue.

Returns: Number of connections currently handled within pool

◆ reapFinishedWorkers()

void DcmBaseSCPPool::reapFinishedWorkers ( )

private

Join and delete all worker threads that have finished handling their association.

Called regularly from the listen loop and from the destructor, so that resources of terminated threads are reclaimed while the pool keeps running.

◆ rejectAssociation()

void DcmBaseSCPPool::rejectAssociation	(	T_ASC_Association *	assoc,
		const T_ASC_RejectParametersReason &	reason )

protected

Reject association using the given reason, e.g. because maximum number of connections is currently already served.

Parameters

assoc	The association to reject
reason	The rejection reason

◆ runAssociation()

OFCondition DcmBaseSCPPool::runAssociation	(	T_ASC_Association *	assoc,
		const DcmSharedSCPConfig &	sharedConfig )

protected

Try to find worker to run the association.

If worker could be found, a side effect is that assoc is set to NULL.

Parameters

assoc	The association to be run. Must be not NULL.
sharedConfig	A DcmSharedSCPConfig object to be used by the worker.

Returns: EC_Normal if worker could be found and runs the association, an error code otherwise.

◆ setMaxThreads()

virtual void DcmBaseSCPPool::setMaxThreads ( const Uint16 maxWorkers )

virtual

Set the number of maximum permitted connections, i.e. threads/workers.

Parameters

maxWorkers Number of threads permitted to exist within pool.

◆ setRunMode()

void DcmBaseSCPPool::setRunMode ( const runmode mode )

private

Thread-safe update of the current run mode, guarded by m_criticalSection.

Parameters

mode	the new run mode to set.

◆ stopAfterCurrentAssociations()

virtual void DcmBaseSCPPool::stopAfterCurrentAssociations ( )

virtual

Request the pool to stop listening for incoming requests.

The listen loop will exit when the current call waiting for a connection request returns (see listen() about blocking vs. non-blocking mode). Workers that are still handling an association finish their work; the destructor waits for all of them to terminate.

Member Data Documentation

◆ m_maxWorkers

Uint16 DcmBaseSCPPool::m_maxWorkers

private

Maximum number of workers that can exist at a time.

Thus limits the maximum number of connections for the pool since every worker serves one connection at a time.

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

dcmnet/include/dcmtk/dcmnet/scppool.h

Classes

Public Member Functions

Protected Member Functions

Private Types

Private Member Functions

Private Attributes

Detailed Description

Member Enumeration Documentation

◆ runmode

Constructor & Destructor Documentation

◆ ~DcmBaseSCPPool()

◆ DcmBaseSCPPool()

Member Function Documentation

◆ createSCPWorker()

◆ dropAndDestroyAssociation()

◆ getConfig()

◆ getMaxThreads()

◆ getRunMode()

◆ initializeNetwork()

◆ listen()

◆ notifyWorkerDone()

◆ numThreads()

◆ reapFinishedWorkers()

◆ rejectAssociation()

◆ runAssociation()

◆ setMaxThreads()

◆ setRunMode()

◆ stopAfterCurrentAssociations()

Member Data Documentation

◆ m_maxWorkers