Feature #2585: Infrastructure supporting external API
API status object
gmxapi milestone 17 as described in #2585
Clients of a GROMACS installation need a robust and well-defined way to manage the results or failure of API operations.
A Status type defines the interface for discovering operation success or failure, plus details.
A consistent Status object interface is portable across Python, C++, and C
Status object can be used to ferry information across API boundaries from exceptions thrown. Exceptions could be chained / status nested.
API client Status objects may be proxies for the actual operation results, allowing deferred and/or non-local execution of operations.
- Should the API (or APIContext) keep a Status singleton? A Status stack? Or should operations create ephemeral Status objects, or objects implementing a Status interface, or should API objects have a Status member?
- What are concerns and solutions for memory allocation for status objects? Should objects own one or generate one on function return?
- How lightweight does a status object need to be? Should the status object contain strings, reference strings mapped by enum, or defer textual messages to messaging and logging facilities?
My inclination is to have a Status object that can hold the success or failure of simple operations, but not to require operations to return a Status object when it is reasonable to return a richer API object. At the very least, there should be a consistent style for accessing details of failures in Status objecst or other API returned types.
Initial implementation could be a very thin wrapper around `bool`, indicating success or failure.
Resolution of this issue enables gmxapi milestone 16 to proceed.
The class is very minimal, but provides a placeholder so
that other API operations have a stable return value. It
is used in cases where some other return value has no
obvious choice or is not implemented.
Relates to gmxapi milestone 17. Refs #2610.
#2 Updated by Eric Irrgang 11 months ago
- Status changed from New to Resolved
gmxapi::Status has been introduced in a minimal form. In general, more useful return values should be produced that do not allow invalid results to go undetected while providing something useful. In cases where there is no clear returned data, but the API operation may have its execution deferred, gmxapi::Status should evolve to encapsulate a "future" style result, but this not addressed in this issue or in GROMACS 2019.