LibSgfcPlusPlus::SgfcBackendController Class Reference

The SgfcBackendController class encapsuslates the SGFC backend and is responsible for coordinating access to it. More...

#include <SgfcBackendController.h>

Public Member Functions
	SgfcBackendController ()
	Initializes a newly constructed SgfcBackendController object that passes no command line arguments to SGFC.
	SgfcBackendController (const std::vector< std::shared_ptr< ISgfcArgument > > &arguments)
	Initializes a newly constructed SgfcBackendController object. All SGFC backend operations performed by the SgfcBackendController object behave according to the specified command line arguments arguments.
virtual	~SgfcBackendController ()
	Destroys and cleans up the SgfcBackendController object.
std::vector< std::shared_ptr< ISgfcArgument > >	GetArguments () const
	Returns the SGFC command line arguments that were used to construct the SgfcBackendController object. The collection is empty if the SgfcBackendController object was constructed with the default constructor.
bool	IsCommandLineValid () const
	Returns true if the SGFC command line arguments that GetArguments() returns are valid. Returns false if they are not valid.
std::shared_ptr< ISgfcMessage >	GetInvalidCommandLineReason () const
	Returns an ISgfcMessage object with message type SgfcMessageType::FatalError that describes why the SGFC command line arguments that GetArguments() returns are not valid. This method may only be invoked if IsCommandLineValid() returns false.
std::shared_ptr< SgfcBackendLoadResult >	LoadSgfFile (const std::string &sgfFilePath)
	Loads a single .sgf file from the specified path and puts it through the SGFC parser. This method may only be invoked if IsCommandLineValid() returns true.
std::shared_ptr< SgfcBackendLoadResult >	LoadSgfContent (const std::string &sgfContent)
	Loads the specified SGF content and puts it through the SGFC parser. This method may only be invoked if IsCommandLineValid() returns true.
std::shared_ptr< SgfcBackendSaveResult >	SaveSgfFile (const std::string &sgfFilePath, std::shared_ptr< SgfcBackendDataWrapper > sgfDataWrapper)
	Saves the SGF content that is encapsulated by sgfDataWrapper to the .sgf file at the specified path sgfFilePath. This method may only be invoked if IsCommandLineValid() returns true.
std::shared_ptr< SgfcBackendSaveResult >	SaveSgfContent (std::string &sgfContent, std::shared_ptr< SgfcBackendDataWrapper > sgfDataWrapper)
	Saves the SGF content that is encapsulated by sgfDataWrapper into the specified string object. This method may only be invoked if IsCommandLineValid() returns true.

Detailed Description

The SgfcBackendController class encapsuslates the SGFC backend and is responsible for coordinating access to it.

SgfcBackendController provides its service to other library-internal classes. The external user of libsgfc++ never comes into direct contact with SgfcBackendController.

When SgfcBackendController is instantiated a set of SGFC command line arguments must be specified that determine how all further SGFC backend operations behave. The SGFC command line arguments cannot be changed after construction. SgfcBackendController validates the arguments and forbids all operations if they are not valid.

After construction SgfcBackendController is responsible for translating load or save operations invoked by the owner of the SgfcBackendController instance into the correct SGFC API calls. This includes:

• Setting up the data structures required by SGFC for its operation
• Applying the command line arguments that were passed to SgfcBackendController on construction
• Capturing the stream of messages generated by SGFC
• Making the results of the operation available to the owner of the SgfcBackendController instance.

In addition SgfcBackendController is responsible for serializing operations that are started concurrently. Unfortunately it is impossible to run SGFC operations in parallel because SGFC uses a global output channel for sending its messages.

Note

If the SGFC message output channel becomes non-global in the future some libsgfc++ things will also have to be changed before concurrent operations can be allowed to run non-serialized. A known class is SgfcSaveStream which uses internal static functions to capture the SGFC save stream.

SGFC has a central memory allocation function (actually a preprocessor macro). When this function fails to allocate memory it invokes an out-of-memory hook/callback to handle the error. The SGFC-internal default hook/callback simply calls exit() and terminates the operating system process. When the first instance of SgfcBackendController is created, that instance installs its own hook/callback which throws std::runtime_error instead of calling exit(). This is done in the remote hope that an out-of-memory situation might possibly be salvaged without terminating the OS process. The SGFC memory allocation function is already invoked when SgfcBackendController is constructed (in the SgfcOption constructor), so when memory allocation fails at that moment one of two things can happen:

• If this is the first instance of SgfcBackendController then the replacement hook/callback has not been installed yet and exit() will be called by SGFC's hook/callback.
• If this is the second or a later instance of SgfcBackendController then the replacement hook/callback has been installed and std::runtime_error will be called by the replacement hook/callback.

Constructor & Destructor Documentation

SgfcBackendController() [1/2]

LibSgfcPlusPlus::SgfcBackendController::SgfcBackendController

(

)

Initializes a newly constructed SgfcBackendController object that passes no command line arguments to SGFC.

Exceptions

std::runtime_error

Is thrown if a memory allocation error occurs. If this is the first SgfcBackendController instance that is created then no exception will be thrown, instead the operating system process will be terminate with a call to exit(). See the SgfcBackendController class documentation for details.

SgfcBackendController() [2/2]

LibSgfcPlusPlus::SgfcBackendController::SgfcBackendController

(

const std::vector< std::shared_ptr< ISgfcArgument > > &

arguments

)

Initializes a newly constructed SgfcBackendController object. All SGFC backend operations performed by the SgfcBackendController object behave according to the specified command line arguments arguments.

Exceptions

std::runtime_error

Is thrown if a memory allocation error occurs. If this is the first SgfcBackendController instance that is created then no exception will be thrown, instead the operating system process will be terminate with a call to exit(). See the SgfcBackendController class documentation for details.

Member Function Documentation

GetInvalidCommandLineReason()

std::shared_ptr< ISgfcMessage > LibSgfcPlusPlus::SgfcBackendController::GetInvalidCommandLineReason

(

)

const

Returns an ISgfcMessage object with message type SgfcMessageType::FatalError that describes why the SGFC command line arguments that GetArguments() returns are not valid. This method may only be invoked if IsCommandLineValid() returns false.

Exceptions

std::logic_error

Is thrown if IsCommandLineValid() returns true.

IsCommandLineValid()

bool LibSgfcPlusPlus::SgfcBackendController::IsCommandLineValid

(

)

const

Returns true if the SGFC command line arguments that GetArguments() returns are valid. Returns false if they are not valid.

One known case where the command line arguments can be invalid is if an illegal parameter is specified for one of the arguments that require a parameter. Example: SgfcArgumentType::BeginningOfSgfData requires an integer parameter. The argument is invalid if an integer value is specified that is not within the accepted range.

There may be other cases. Invoke GetInvalidCommandLineReason() to learn the actual reason why the command line arguments are not valid.

LoadSgfContent()

std::shared_ptr< SgfcBackendLoadResult > LibSgfcPlusPlus::SgfcBackendController::LoadSgfContent

(

const std::string &

sgfContent

)

Loads the specified SGF content and puts it through the SGFC parser. This method may only be invoked if IsCommandLineValid() returns true.

Returns

An SgfcBackendLoadResult object that holds the result of the load operation. Notably if the operation was successful the result object contains the SGF content that was loaded.

Exceptions

std::logic_error

Is thrown if IsCommandLineValid() returns false.

LoadSgfFile()

std::shared_ptr< SgfcBackendLoadResult > LibSgfcPlusPlus::SgfcBackendController::LoadSgfFile

(

const std::string &

sgfFilePath

)

Loads a single .sgf file from the specified path and puts it through the SGFC parser. This method may only be invoked if IsCommandLineValid() returns true.

Returns

An SgfcBackendLoadResult object that holds the result of the load operation. Notably if the operation was successful the result object contains the SGF content that was loaded.

Exceptions

std::logic_error

Is thrown if IsCommandLineValid() returns false.

SaveSgfContent()

std::shared_ptr< SgfcBackendSaveResult > LibSgfcPlusPlus::SgfcBackendController::SaveSgfContent	(	std::string &	sgfContent,
		std::shared_ptr< SgfcBackendDataWrapper >	sgfDataWrapper )

Saves the SGF content that is encapsulated by sgfDataWrapper into the specified string object. This method may only be invoked if IsCommandLineValid() returns true.

The previous content of sgfContent is overwritten.

Before SgfcBackendController can invoke the SGFC save function, it needs to pass the SGF content through SGFC's load/parse functions. The messages in the result object therefore are a combination of a full cycle of SGFC load/parse/save operations.

Returns

An SgfcBackendSaveResult object that holds the result of the save operation.

Exceptions

std::logic_error

Is thrown if IsCommandLineValid() returns false.

SaveSgfFile()

std::shared_ptr< SgfcBackendSaveResult > LibSgfcPlusPlus::SgfcBackendController::SaveSgfFile	(	const std::string &	sgfFilePath,
		std::shared_ptr< SgfcBackendDataWrapper >	sgfDataWrapper )

Saves the SGF content that is encapsulated by sgfDataWrapper to the .sgf file at the specified path sgfFilePath. This method may only be invoked if IsCommandLineValid() returns true.

If a file already exists at the specified path it is overwritten.

Before SgfcBackendController can invoke the SGFC save function, it needs to pass the SGF content through SGFC's load/parse functions. The messages in the result object therefore are a combination of a full cycle of SGFC load/parse/save operations.

Returns

An SgfcBackendSaveResult object that holds the result of the save operation.

Exceptions

std::logic_error

Is thrown if IsCommandLineValid() returns false.

---

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

• /Users/patrick/dev/libsgfcplusplus/src/sgfc/backend/SgfcBackendController.h
• /Users/patrick/dev/libsgfcplusplus/src/sgfc/backend/SgfcBackendController.cpp