Client API philosophy - minutes of meeting

[Alan Griffiths]

To help resolve this discussion Thomas Voss called a meeting at 9:00UTC
11-11-2014

Those attending:
Thomas Voss
Christopher James Halse Rogers
Alan Griffiths
Alexandros Frantzis
Andreas Pokorny

Apologies:
Daniel van Vugt

1. We started with a recap over some design goals:

1.1 The server should be in control of "policy"
1.2 It should be easy to validate use of the client API

Thomas noted that he saw no need to support re-parenting - there was no
disagreement.

We discussed the several design approaches being discussed - including
the "parenting" proposals from Daniel and the "two-stage-surface-create"
proposal from Chris and variations from various discussions. These were
assessed against the needs of the user of the client API and the needs
of the server to decide presentation policy.

Consensus was reached around the following:

For each type of surface there should be a corresponding "builder" type.
We used creation of a "menu" to illustrate the canonical form of surface
creation (note the names here are illustrative, not prescriptive)...

    // allocate a builder with all required parameters
    MirSurfaceBuilder* menu_builder =
    mir_connection_allocate_menu_builder(connection, /* any required
    parameters (e.g. parent) */);
    ...
    // set any optional attributes
    mir_surface_bulder_set_XXX(menu_builder, xxx);

    // Finally, create the surface
    MirSurface* surface =
    mir_surface_bulder_create_surface_sync(menu_builder);


This approach had the following advantages:

1. The type of surface is determined explicitly
2. Provision of required parameters is validated at compile time
3. MirSurfaceBuilder and MirSurface are opaque types

Note that discovering new "required" parameters is an API break and this
approach ensures affected code is identified at compile time.

Re the "parenting" branches: "parent" is only ever provided as part of
builder creation (and supplied to the server at surface creation time).
Re-parenting isn't to be supported. These branches need reworking
accordingly.

Actions:

Chris: to update his branch to have a separate builder object. (This
also addresses concerns about functions that behave differently between
pre-realize and post-realize.)

Alan: write minutes
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.ubuntu.com/archives/mir-devel/attachments/20141111/7336f24b/attachment.html>