Chapter 7
Backends

To maximise this separation there is no direct function call interface to the backend themselves. By enforcing this we allow the backends to be changed and updated frequently without breaking existing programs.

Sometimes one wishes to write some backend specific code however, and control it through Sh. This might be necessary to make use of functionality offered by a particular backend but not exposed by the Sh API. This can done by setting metadata in the form of arbitrary name-value pairs on Sh objects. A backend can check for metadata, but metadata interpretation is entirely up to and specific to each particular backend. See Section 2.7 for details on metadata in general.

An application must provide at least one choice of backend to Sh. The simplest way to do this is to call the shSetBackend(std::string) function, which takes a string consisting of the backend’s name. This will cause any future interactions with the backend to use only that backend. If the specified backend is unavailable an ShBackendException error will be signalled.

/ It may be useful to specify a list of possible backends, and use the most appropriate one for a particular program. This can be done using the shUseBackend(std::string) function. Each call to this function will add the given backend to the end of a list of potential backends. The first appropriate backend in the list for a particular ShProgram will then be chosen. To clear the list of backends call shClearBackends(). A call to shSetBackend also clears the list of backends before adding the given backend as the only item.

/ To check if a particular backend is available, call the shHaveBackend function with a std::string argument specifying the backend’s name. This function returns an integer indicating the version of the given backend which is available. If the backend is unavailable it returns zero.

Note: This manual is available as a bound book from AK Peters, including better formatting, in-depth examples, and about 200 pages not available on-line.