TT Client Library 1.0.0
C++ library for Tandem Tales clients.
Loading...
Searching...
No Matches
tt::ClientFactory Class Referenceabstract

A client factory continuously creates clients to connect to a server and is useful for deploying automated agents. More...

#include <tt/ClientFactory.h>

Public Member Functions

 ClientFactory (int maxClients)
 Creates a new client factory with an upper limit on the number of clients that it will create simultaneously.
 ClientFactory ()
 Creates a new client factory with no upper limit on the number of clients that may run simultaneously.
virtual std::string toString () const
 Gives a string representation of this client factory.
void execute ()
 This method starts the client factory, creates the first client, periodically creates new clients as needed, and shuts down gracefully if the factory is closed or if a client throws an uncaught exception.
void close ()
 Causes the factory to shut down gracefully, closing any waiting clients and waiting for any running clients to finish.
void onStart (const Client *client)
 This method is called from the client's call method when the client begins its session.

Public Attributes

const int maxClients
 The maximum number of clients that this factory will create to run simultaneously.

Protected Member Functions

virtual void onStart () const
 This method is called once when this factory begins running.
virtual client_ptr create () const =0
 This method creates and returns a new client of the type produced by this factory.
virtual void onClose () const
 This method is called once after this factory stops creating new clients and has begun shutting down.
virtual void onStop () const
 This method is called once at the end of this factory's shutdown process after all clients have stopped running.

Friends

std::ostream & operator<< (std::ostream &os, const ClientFactory &a)
 Override stream insertion operator to allow printing the ClientFactory class.

Detailed Description

A client factory continuously creates clients to connect to a server and is useful for deploying automated agents.

A factory starts by creating one client to join the server's queue of waiting players. When that client finds a partner and starts its session, the factory creates a new client to take its place in the queue.

You can limit the maximum number of clients this factory will run simultaneously.

If any client created by this factory throws an uncaught exception, this factory will shut down gracefully and throw that exception after shutting down.

This class provides several methods that are all called from the same thread at important moments in the factory's lifecycle. These methods can be overridden to, for example, log important information. See the execute() method for a full description of these methods and when they are called.

Author
Gage Birchmeier

Constructor & Destructor Documentation

◆ ClientFactory() [1/2]

tt::ClientFactory::ClientFactory ( int maxClients)

Creates a new client factory with an upper limit on the number of clients that it will create simultaneously.

Parameters
maxClientsthe maximum number of clients that may be running simultaneously

◆ ClientFactory() [2/2]

tt::ClientFactory::ClientFactory ( )

Creates a new client factory with no upper limit on the number of clients that may run simultaneously.

Creates a new client factory with the hardware concurrency as the limit on the number of clients that may run simultaneously.

Member Function Documentation

◆ close()

void tt::ClientFactory::close ( )

Causes the factory to shut down gracefully, closing any waiting clients and waiting for any running clients to finish.

This method can be called safely from any thread. It will cause the thread which called execute() to stop creating new clients, to call the onClose() method, to close all clients whose sessions have not started, to wait for all clients whose sessions have started to end, and finally to stop.

◆ create()

virtual client_ptr tt::ClientFactory::create ( ) const
protectedpure virtual

This method creates and returns a new client of the type produced by this factory.

The factory will always call this method from the thread which called execute().

Returns
a new instance of the client this factory produces
Exceptions
Exceptionif a problem occurred while creating the client

◆ execute()

void tt::ClientFactory::execute ( )

This method starts the client factory, creates the first client, periodically creates new clients as needed, and shuts down gracefully if the factory is closed or if a client throws an uncaught exception.

As this method runs, it calls other methods to notify the factory of important events. Some of these methods are guaranteed to be called even if an exception is thrown. The list of those methods and when they happen is as follows:

  • The onStart() method is called first. If this method throws an exception it is thrown immediately, and no other methods are called.
  • The first client is created and runs on a new thread.
  • Each time a client starts its session, a new client will be created to take its place in the server's queue of waiting clients. If creating a new client would exceed this factory's limit on the number of clients which can run simultaneously, this factory will wait until a running client has completed its session to start the next client.
  • If one of the clients created by this factory throws an exception, or if the close() method is called, the onClose() method will run on the thread which called this method, regardless of which thread called close(). If the thread which called this method is interrupted, onClose() will not be called.
  • Any clients whose sessions have not yet begun will be closed. Clients whose sessions have begun will not be closed. If this factory stopped because of an exception or because the close() method was called, it will wait for all clients whose sessions have started to finish. If this factory stopped because the thread which called this method was interrupted, it will not wait for running clients to finish their sessions.
  • After all running clients have finished their sessions, onStop() is called. If this factory stopped because the thread which called this method was interrupted, that method will not be called.
  • If a client threw an exception, that exception will be thrown from this method.

◆ onClose()

virtual void tt::ClientFactory::onClose ( ) const
inlineprotectedvirtual

This method is called once after this factory stops creating new clients and has begun shutting down.

This method is called either because this factory was closed or because a client threw an exception. This method will always be called from the thread which called execute(). This method will not be called if the client shuts down because the execute() method was interrupted.

By default, this method does nothing. It can be overridden if the factory wants to do something when the factory first begins shutting down.

Exceptions
Exceptionif a problem occurred during this method

◆ onStart() [1/2]

virtual void tt::ClientFactory::onStart ( ) const
inlineprotectedvirtual

This method is called once when this factory begins running.

By default, this method does nothing. It can be overridden if the factory wants to do something when the factory first begins running.

Exceptions
Exceptionif a problem occurred during this method

◆ onStart() [2/2]

void tt::ClientFactory::onStart ( const Client * client)

This method is called from the client's call method when the client begins its session.

If the client limit allows, this method will cause the factory to create a new client to take the starting client's place in the server's queue of waiting clients.

Parameters
clienta client created by this factory whose session has started

◆ onStop()

virtual void tt::ClientFactory::onStop ( ) const
inlineprotectedvirtual

This method is called once at the end of this factory's shutdown process after all clients have stopped running.

This method will always be called from the thread which called execute(). This method will not be called if the client shuts down because the execute() method was interrupted.

By default, this method does nothing. It can be overridden if the factory wants to do something just before the factory stops running.

Exceptions
Exceptionif a problem occurred during this method

◆ toString()

std::string tt::ClientFactory::toString ( ) const
virtual

Gives a string representation of this client factory.

Returns
a string representation of this client factory.

◆ operator<<

std::ostream & operator<< ( std::ostream & os,
const ClientFactory & a )
friend

Override stream insertion operator to allow printing the ClientFactory class.

Parameters
osan output stream to insert into
aa reference to a client factory object
Returns
the output stream referenced

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