Client API philosophy

Tue Nov 11 02:59:49 UTC 2014

On Tue, Nov 11, 2014 at 1:40 PM, Daniel van Vugt 
<daniel.van.vugt at canonical.com> wrote:
> So given invalid states are easily rejected by the shell and what mode
> it's in, and given it's unrealistic (predicting the future) and
> undesirable (scales poorly) to design all future shells behaviours 
> into
> separate functions of a client API, I came up with the normalised 
> design
> you see today.
> 
> People often get confused about why I mention database normalization 
> in
> API design, but the principles and objectives are the same:
>    http://en.wikipedia.org/wiki/Database_normalization

At least one difference being that the database has a schema which 
enforces the constraints for you. If you take that approach for API 
design it means you need to implement all the constraints yourself; 
you've lost the help of the compiler in doing so.

> 
> On 11/11/14 10:22, Daniel van Vugt wrote:
> > There is no invalid state possible, providing all attributes have 
> some
> > default value, and all modifications to an attribute are 
> synchronously
> > validated (or rejected) on the server side. And it's not even 
> important
> > if you allow a slight semantic reordering (i.e. "invalid" state):
> >     set_parent(a, b);
> >     set_relative_pos(a, x, y);
> > vs
> >     set_relative_pos(a, x, y);  <-- temporary inconsistency
> >     set_parent(a, b);
> > so you can treat the inconsistency as an error or support it on the
> > assumption that a parent will be provided. Or support it on the
> > assumption that parentless relative positioning has meaning (e.g. to
> > position a client-rendered panel/dock).
> >
> > I know the third option is unpopular, but my point is that there 
> are at
> > least three options and it really doesn't matter what we choose.
> >
> > Remember we are writing asynchronous client functions so they don't
> > return errors immediately. Rather you can optionally wait for their
> > completion and then query what actually happened.
> >
> >
> > On 11/11/14 10:12, Christopher James Halse Rogers wrote:
> >>
> >>
> >> On Tue, Nov 11, 2014 at 12:48 PM, Daniel van Vugt
> >> <daniel.van.vugt at canonical.com> wrote:
> >>> On the second issue of client API design, it's useful to point 
> out why
> >>> the menu example is not a good argument:
> >>>
> >>> 1. Depending on your shell, and its current mode, a "menu" might 
> not
> >>> have a relative position dictated by the window position, but get
> >>> moved/modified elsewhere on the screen. Think about phones where 
> long
> >>> menus/combos get converted to a wheel/widget in the centre of the
> >>> screen (mostly phones).
> >>
> >> Oh, absolutely. It's fine for the shell to interpret the requested
> >> coordinates as appropriate for the form-factor. Indeed, we fully 
> expect
> >> *desktop* shells to interpret the coordinates as appropriate (for
> >> example, if the requested surface would be mostly offscreen if 
> (x,y)
> >> were interpreted as its top-left coordinate).
> >>
> >>>
> >>> 2. Relative position is useful to other window types too. For 
> example
> >>> the decorations-next design of title bars, but also embedded GL
> >>> windows or accelerated video in a browser. So with multiple 
> features
> >>> requiring relative placement, you propose each new feature gets a 
> new
> >>> client function, which is mostly redundant with the others? That's
> >>> crazy for three reasons:
> >>>   (a) Redundancy in the API is unwanted effort, particularly for
> >>> maintenance. It scales poorly.
> >>
> >> The APIs are really simple - I'm perfectly happy if they're all
> >> implemented in terms of integer surface parameters!
> >>
> >> And the maintenance effort is traded off between more distinct API 
> entry
> >> points and easier state validation; if you can't atomically set 
> all the
> >> necessary attributes on a surface then the surface must transition
> >> through an invalid state.
> >>
> >> If your client API prototypes require all the relevant state to be
> >> provided up-front it's much easier to verify correctness.
> >>
> >>>
> >>>   (b) Each function, by its name, is tied to a window type (e.g.
> >>> "menu") and so could easily become deprecated as desired
> >>> types/functionality changes.
> >>>   (c) Your proposed API that ties a "menu" to (x,y) now has
> >>> unused/ignored parameters in phone (or other) shells that ignore 
> the
> >>> (x,y) for menus (see #1 above).
> >>
> >> Equally, if you *don't* have (x,y) for the menu your client is now 
> tied
> >> exclusively to the phone and will mysteriously die if you try it 
> on a
> >> desktop.
> >>
> >> The semantic for menus may well be “this pops up a surface 
> associated
> >> with <rectangle> when appropriate”. That's perfectly fine.
> >>
> >>>
> >>> On 11/11/14 09:33, Daniel van Vugt wrote:
> >>>> We are actually in violent agreement on "policy" and conflating 
> two
> >>>> different issues. So please, let's separate them :)
> >>>>
> >>>> It is indeed up to the server/shell to dictate policy, 
> particularly as
> >>>> it can and will vary between shells/modes of a shell. Anything 
> invalid
> >>>> is returned as an error to the client API, or in the form of a
> >>>> non-blocking API:
> >>>>
> >>>>    1. asynchronous set feature A = B
> >>>>    2. optional wait and get feature A, and check it was changed 
> to B or
> >>>> something else dictated by shell policy.
> >>>>
> >>>> What we must not do is try to enforce policy via client function
> >>>> prototype design. Because policy changes not just between 
> shells, but
> >>>> even between modes of a shell (e.g. we aim to unify Unity8 
> desktop with
> >>>> touch I think).
> >>>>
> >>>> The confusion here is coming from some people thinking that a 
> flexible
> >>>> API prevents strong enforcement of policy. It does not.
> >>>>
> >>>> P.S. "menus" are explicitly not a window type right now (as 
> copied from
> >>>> the WM design docs). So it's possibly assuming too much to 
> mention the
> >>>> the word "menu" in the client API. Although we possibly could - 
> rename
> >>>> popover?
> >>>>
> >>>>
> >>>> On 10/11/14 17:58, Alan Griffiths wrote:
> >>>>> On 10/11/14 03:31, Daniel van Vugt wrote:
> >>>>>>
> >>>>>> Sounds like a response to one of my merge proposals. So please 
> put
> >>>>>> arguments in the code reviews...
> >>>>>
> >>>>> There's a good reason to discuss this outside of a specific code
> >>>>> review:
> >>>>> we need to agree the "big picture".
> >>>>>
> >>>>> There is an apparent disagreement about the approach to window
> >>>>> management policy and that affects the review of any and all 
> MPs in
> >>>>> this
> >>>>> area.
> >>>>>
> >>>>> I've always understood the intent to be that Mir enables shells 
> (in
> >>>>> general and specifically unity8) to implement policies about how
> >>>>> things
> >>>>> should be presented. It is far easier for a shell to provide a 
> policy
> >>>>> around, say "menus" if it is asked to "show a menu" than if it 
> is
> >>>>> asked
> >>>>> for a window, then asked to "parent" it, then asked to position 
> it,
> >>>>> etc.
> >>>>> With this approach there is never any point at which the server 
> knows
> >>>>> what the client intends.
> >>>>>
> >>>>> If we intend to push the presentation policy out to the client
> >>>>> toolkits
> >>>>> then they will provide inconsistent (a.k.a. incorrect) policy
> >>>>> implementations. (Especially if, as we should hope, there are 
> multiple
> >>>>> shells written using the Mir library that implement policies
> >>>>> differently.)
> >>>>>
> >>>>>
> >>>>>
> >>>>
> >>>
> >>> --
> >>> Mir-devel mailing list
> >>> Mir-devel at lists.ubuntu.com
> >>> Modify settings or unsubscribe at:
> >>> https://lists.ubuntu.com/mailman/listinfo/mir-devel
> >>
> >>
> >
> 
> --
> Mir-devel mailing list
> Mir-devel at lists.ubuntu.com
> Modify settings or unsubscribe at: 
> https://lists.ubuntu.com/mailman/listinfo/mir-devel