Client API philosophy

Tue Nov 11 02:22:21 UTC 2014

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
>
>