Base class for GTP (Go Text Protocol) engines. More...

#include <GtpEngine.h>

Public Member Functions
	GtpEngine ()
virtual	~GtpEngine ()
void	ExecuteFile (const std::string &name, std::ostream &log=std::cerr)
	Execute commands from file.
std::string	ExecuteCommand (const std::string &cmd, std::ostream &log=std::cerr)
	Execute a single command string.
void	MainLoop (GtpInputStream &in, GtpOutputStream &out)
	Run the main command loop.
void	Register (const std::string &name, GtpCallbackBase *callback)
	Register command handler.
template<class T >
void	Register (const std::string &command, typename GtpCallback< T >::Method method, T *instance)
	Register a member function as a command handler.
bool	IsRegistered (const std::string &command) const
	Returns if command registered.
void	SetQuit ()
	Set flag for quitting the main command loop.
bool	IsQuitSet () const
	Did the last command set the quit flag?
virtual void	Ponder ()
	Ponder.
virtual void	InitPonder ()
	Prepare for pondering.
virtual void	StopPonder ()
	Stop pondering.
virtual void	Interrupt ()
	Interrupt the current command.
Command Callbacks

virtual void	CmdKnownCommand (GtpCommand &)
	Return `true` if command is known, `false` otherwise.
virtual void	CmdListCommands (GtpCommand &)
	List all known commands.
virtual void	CmdName (GtpCommand &)
	Return name.
virtual void	CmdProtocolVersion (GtpCommand &)
	Return protocol version.
virtual void	CmdQuit (GtpCommand &)
	Quit command loop.
virtual void	CmdVersion (GtpCommand &)
	Return empty version string.
Protected Member Functions
virtual void	BeforeHandleCommand ()
	Hook function to be executed before each command.
virtual void	BeforeWritingResponse ()
	Hook function to be executed before the response of a command is written.
Private Types
typedef std::map< std::string, GtpCallbackBase * >	CallbackMap
Private Member Functions
	GtpEngine (const GtpEngine &engine)
	Not to be implemented.
GtpEngine &	operator= (const GtpEngine &engine) const
	Not to be implemented.
bool	HandleCommand (GtpCommand &cmd, GtpOutputStream &out)
Private Attributes
bool	m_quit
CallbackMap	m_callbacks

Detailed Description

Base class for GTP (Go Text Protocol) engines.

Commands can be added with GtpEngine::Register(). Existing commands can be overridden by registering a new handler for the command or by overriding the command handler member function in subclasses.

See also:: GtpEngine Commands, Simulated Delays

Bug:: With newer versions of Boost, there is an assertion triggered in debug mode if a GTP command handler throws an exception other than GtpFailure. See http://sourceforge.net/apps/trac/fuego/ticket/59

Definition at line 569 of file GtpEngine.h.

Member Typedef Documentation

typedef std::map<std::string,GtpCallbackBase*> CallbackMap [private]

Definition at line 710 of file GtpEngine.h.

Constructor & Destructor Documentation

GtpEngine ( )

Definition at line 621 of file GtpEngine.cpp.

References CmdKnownCommand(), CmdListCommands(), CmdName(), CmdProtocolVersion(), CmdQuit(), CmdVersion(), and Register().

~GtpEngine ( ) [virtual]

Definition at line 632 of file GtpEngine.cpp.

References m_callbacks.

GtpEngine ( const GtpEngine & engine ) [private]

Not to be implemented.

Member Function Documentation

void BeforeHandleCommand ( ) [protected, virtual]

Hook function to be executed before each command.

Default implementation does nothing.

Definition at line 644 of file GtpEngine.cpp.

Referenced by HandleCommand().

void BeforeWritingResponse ( ) [protected, virtual]

Hook function to be executed before the response of a command is written.

Default implementation does nothing.

Definition at line 649 of file GtpEngine.cpp.

Referenced by HandleCommand().

void CmdKnownCommand ( GtpCommand & cmd ) [virtual]

Return true if command is known, false otherwise.

Definition at line 655 of file GtpEngine.cpp.

References GtpCommand::Arg(), IsRegistered(), and GtpCommand::SetResponseBool().

Referenced by GtpEngine().

void CmdListCommands ( GtpCommand & cmd ) [virtual]

List all known commands.

Definition at line 661 of file GtpEngine.cpp.

References GtpCommand::CheckArgNone(), and m_callbacks.

Referenced by GtpEngine().

void CmdName ( GtpCommand & cmd ) [virtual]

Return name.

Definition at line 670 of file GtpEngine.cpp.

References GtpCommand::CheckArgNone().

Referenced by GtpEngine().

void CmdProtocolVersion ( GtpCommand & cmd ) [virtual]

Return protocol version.

Definition at line 677 of file GtpEngine.cpp.

References GtpCommand::CheckArgNone().

Referenced by GtpEngine().

void CmdQuit ( GtpCommand & cmd ) [virtual]

Quit command loop.

Definition at line 684 of file GtpEngine.cpp.

References GtpCommand::CheckArgNone(), and SetQuit().

Referenced by GtpEngine().

void CmdVersion ( GtpCommand & cmd ) [virtual]

Return empty version string.

The GTP standard says to return empty string, if no meaningful reponse is available.

Definition at line 693 of file GtpEngine.cpp.

References GtpCommand::CheckArgNone().

Referenced by GtpEngine().

string ExecuteCommand	(	const std::string &	cmd,
		std::ostream &	log = `std::cerr`
	)

Execute a single command string.

Parameters:

	cmd	The command line
	log	Stream for logging the command and response to (default is std::cerr).

Returns:: The command response

Exceptions:

GtpFailure

If the command fails

Definition at line 698 of file GtpEngine.cpp.

References HandleCommand(), GtpCommand::Init(), GtpCommand::Line(), and GtpCommand::Response().

void ExecuteFile	(	const std::string &	name,
		std::ostream &	log = `std::cerr`
	)

Execute commands from file.

Aborts on the first command that fails.

Parameters:

	name	The file name
	log	Stream for logging the commands and responses to (default is std::cerr).

Exceptions:

GtpFailure

If a command fails

Definition at line 713 of file GtpEngine.cpp.

References HandleCommand(), GtpCommand::Init(), and GtpCommand::Line().

bool HandleCommand	(	GtpCommand &	cmd,
		GtpOutputStream &	out
	)			`[private]`

Definition at line 734 of file GtpEngine.cpp.

References BeforeHandleCommand(), BeforeWritingResponse(), GtpOutputStream::Flush(), GtpCommand::ID(), m_callbacks, GtpCommand::Name(), GtpFailure::Response(), GtpCommand::Response(), and GtpOutputStream::Write().

Referenced by ExecuteCommand(), ExecuteFile(), and MainLoop().

void InitPonder ( ) [virtual]

Prepare for pondering.

See also:: Ponder() The default implementation does nothing.

Definition at line 860 of file GtpEngine.cpp.

void Interrupt ( ) [virtual]

Interrupt the current command.

This function implements interrupt functionality as used by GoGui. It will be called from a different thread that the command thread when the special command line # interrupt is received. The default implementation does nothing.

Definition at line 873 of file GtpEngine.cpp.

bool IsQuitSet ( ) const

Did the last command set the quit flag?

Definition at line 836 of file GtpEngine.cpp.

References m_quit.

bool IsRegistered ( const std::string & command ) const

Returns if command registered.

Definition at line 772 of file GtpEngine.cpp.

References m_callbacks.

Referenced by CmdKnownCommand().

void MainLoop	(	GtpInputStream &	in,
		GtpOutputStream &	out
	)

Run the main command loop.

Reads lines from input stream, calls the corresponding command handler and writes the response to the output stream. Empty lines in the command responses will be replaced by a line containing a single space, because empty lines are not allowed in GTP responses.

Parameters:

	in	Input GTP stream
	out	Output GTP stream

Definition at line 777 of file GtpEngine.cpp.

References HandleCommand(), m_quit, and SetQuit().

GtpEngine& operator= ( const GtpEngine & engine ) const [private]

Not to be implemented.

void Ponder ( ) [virtual]

Ponder.

This function will be called in MainLoop() while the engine is waiting for the next command. It will be called after InitPonder() from a different thread than the command thread, but only while waiting for the next command, so no concurrent execution of this function and other engine functions is possible. The function should return immediately when StopPonder() is called. InitPonder() and StopPonder() are called from the command thread. In a typical implementation, InitPonder() will clear an abort flag and StopPonder() will set it. Ponder() will poll the abort flag and return when it is set (or it has nothing to do; or some maximum time limit for pondering was exceeded). The default implementation does nothing and returns immediately.

Definition at line 844 of file GtpEngine.cpp.

void Register	(	const std::string &	name,
		GtpCallbackBase *	callback
	)

Register command handler.

Takes ownership of callback. If a command was already registered with the same name, it will be replaced by the new command.

Definition at line 817 of file GtpEngine.cpp.

References m_callbacks.

Referenced by GtpEngine(), and Register().

void Register	(	const std::string &	command,
		typename GtpCallback< T >::Method	method,
		T *	instance
	)

Register a member function as a command handler.

If a command was already registered with the same name, it will be replaced by the new command.

Definition at line 726 of file GtpEngine.h.

References Register().

void SetQuit ( )

Set flag for quitting the main command loop.

Currently, this function works only for the "quit" command, if the engine is compiled with interrupt functionality (GTENGINE_INTERRUPT). Therefore, it is not possible for other commands to decide to quit (which would be necessary for instance to implement a maximal game number if playing on KGS and deciding to quit on the kgs-game_over command, if the maximum number is reached).

The reason is that the command stream is then read from a different thread using a blocking, non-interruptible read function, which is entered before the command handler is invoked in the main thread. Because of the non-interruptible read function, the implementation of GtpEngine needs to know what commands will quit to avoid entering this read function after a quit.

If a way is found to interrupt the read thread during the execution of the blocking std::getline (maybe in a future version of Boost.Thread), this function could also be called in other GTP commands.

See also:: MainLoop()

Definition at line 831 of file GtpEngine.cpp.

References m_quit.

Referenced by CmdQuit(), and MainLoop().

void StopPonder ( ) [virtual]

Stop pondering.

See also:: Ponder() The default implementation does nothing.

Definition at line 852 of file GtpEngine.cpp.

Member Data Documentation

CallbackMap m_callbacks [private]

Definition at line 714 of file GtpEngine.h.

Referenced by CmdListCommands(), HandleCommand(), IsRegistered(), Register(), and ~GtpEngine().

bool m_quit [private]

Definition at line 712 of file GtpEngine.h.

Referenced by IsQuitSet(), MainLoop(), and SetQuit().

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

GtpEngine Class Reference

Public Member Functions

Protected Member Functions

Private Types

Private Member Functions

Private Attributes

Detailed Description

Member Typedef Documentation

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation