An overview of the goals and design principles of Starboard with the perspective of hindsight.
Status: REVIEWED
Created: 2016-11-12
Starboard is a porting abstraction and a collection of implementation fragments used to abstract operating system facilities and platform quirks from C or C++ applications. It occupies a similar space to SDL, DirectFB, Marmalade, and various others.
Starboard was created as a response to the significant effort it has historically taken to port desktop-oriented web browsers to non-traditional device platforms like game consoles. Chromium in particular mixes platform-specific code with common code throughout the technology stack, making it very difficult to know what has to be done for a new platform or how much work it is going to be.
Here are the main goals of Starboard, stack-ranked from most-to-least important.
APIs can generally be augmented without serious backwards-compatibility consequences, but they can not be changed or pruned so easily, so it is better to err on the side of providing less.
A broader specification of the behavior of an API function makes life easier for the implementor, but more difficult for anyone attempting to use the API. An API can be so weakly specified that it is not usable across platforms. It can also be so strictly specified that it is not implementable across platforms. Err on the side of narrower specifications, requiring generality only when necessitated by one or more platforms.
For example, passing in a set of string-string name-value pairs. This takes the compiler out of any kind of validation, and can encourage mismatches of understanding between Clients and Platforms.
Whenever adding or changing an API, or specifying a contract, consider whether this places a large burden on some platform implementers. This burden could be because of a wide porting surface, or complex requirements that are difficult to implement. It could be caused by a fundamental piece of infrastructure that isn't provided by a particular platform.
We can always make APIs that are burdensome to use easier with more common code.
Consistency, not just in formatting, but in semantics, leads to predictability. Some people just won‘t read the documentation, even if it’s thorough. Perhaps especially if it's thorough. The names of API entities should convey the intention as completely as possible.
Yet, overly-verbose naming will make the API difficult to remember, read, and use.
Engineers from a broad set of backgrounds and environments will end up being dropped into porting Starboard. They may not have knowledge of any particular technologies, best practices, or design patterns. They may be under an aggressive deadline.
Each function and module should have a strategy for dealing with multiple threads. It should make sense for the expected use cases of the interface entities in question. As the interface designer, it is most clear to you how the API should be used with respect to threads.
Some may be “thread-safe,” such that any functions can be called from any thread without much concern. Note that this places the burden on the implementer to ensure that an implementation meets that specification, and they MAY not know how to do that. This can also be more complex than just acquiring a mutex inside every function implementation, as there may be inherent race conditions between function calls even when using a synchronization mechanism.
The path of least burden to the porter is to say that an interface is not thread-safe at all, which means applications will have to take care how the API is used. But, sometimes even this requires clarification as to what modes of access are dangerous and how to use the API safely.
“Informational-Only” is defined by a result code that doesn't change the behavior of the caller. Many times, why something failed does not matter when the product is already in the hands of the user. We often want diagnostic logging during development
Starboard has a versioning mechanism to manage change.