It's now done. Only lockOrientation() uses promises. There isn't much usefulness in using that for unlock orientation given that the default orientation value might be unknown to the browser so the developers might call unlockOrientation() but the UA couldn't know if there will be an orientationchange event following so the promise could stay pending forover.

Change made here:
https://dvcs.w3.org/hg/screen-orientation/rev/24701e870b89
But serious clean-up here:
https://dvcs.w3.org/hg/screen-orientation/rev/d42347e9ab3d

Probably simpler to look at the current specification document.

Hi Mounir,

I'm doing a quick review of the promise usage here and had a few questions and comments. I hope they're helpful.

----

> 4. If a promise previously created in these steps is pending, it MUST be rejected with a DOMException whose name is AbortError.

This was very confusing, since the promise was previously created in step 3. Upon re-reading, I understood that you actually meant something like the following:

- Upon window creation, create an empty list of pending lock-orientation promises.
- After creating _promise_ in step 3, add it to the list of pending lock-orientation promises.
- In step 4, loop through the list of pending lock-orientation promises and reject them with an AbortError; then empty the list.

This would be a much clearer formulation of the situation.

----

> 3. Let promise be a newly-created promise and return it.

Since you have returned in step 3, steps 4 onward will never run. You should return the promise at the end of the algorithm. There are examples at https://github.com/w3ctag/promises-guide#examples which may help.

-----

> 9. Otherwise, the next time the orientation changes, before firing the orientationchange event, resolve promise with result. 

What is this "otherwise" attached to? Its closest sibling, 8, is not an "if." Is it meant to be attached to 8.3? If so, it should be inside the queued task.

Furthermore, I don't understand why you would have this clause at all. The idea is, if the orientation is already locked, then you should not resolve the promise, but wait for the user to turn their screen? That seems unrelated. It seems to me to make more sense to always resolve the promise after locking, even if locking the orientation does not result in an orientation change. Since the operation that the promise represents is in fact "locking the orientation."

-----

> void unlockOrientation ();

Is unlocking the orientation always synchronous? That is, can the caller depend on the orientation being unlocked immediately after making the `unlockOrientation()` call?

It seems like not, since

> The unlockOrientation() method, when invoked, MUST asynchronously lock the orientation to the default orientation

In that case, a promise should be used so that users can reason about their program in the sense of knowing when the orientation is finished unlocking.

Reopening, as Domenic's feedback has not been addressed.

> In step 4, loop through the list of pending lock-orientation promises and reject them with an AbortError; then empty the list.

Technically, Domenic is correct. However, I don't think you can (or should) end up with a list of pending promises. At most, you would end up with 1 pending promise at any point in time. This is because:

```JS

//this creates a promise, puts it in the pending queue. 
var p1 = lockOrientation();

//This will cause p1 to be immediately rejected with an AbortError.
//This now puts p2 in the place of p1 in the pending queue. 
var p2 = lockOrientation();

//And so on... p2 is rejected, pN is queued.  
var pN =  lockOrientation();

```

(In reply to Domenic Denicola from comment #2)
> > void unlockOrientation ();
> 
> Is unlocking the orientation always synchronous? That is, can the caller
> depend on the orientation being unlocked immediately after making the
> `unlockOrientation()` call?
> 
> It seems like not, since
> 
> > The unlockOrientation() method, when invoked, MUST asynchronously lock the orientation to the default orientation
> 
> In that case, a promise should be used so that users can reason about their
> program in the sense of knowing when the orientation is finished unlocking.

We can't reliably know when the unlock is done given that it means that we lock to the default orientation which might be platform specific and the browser might not actually know it. I don't even mention odd behaviours like Android on phones that will accept portrait-secondary if you locked to 'any', will not accept you to switch to that orientation if you are locked to the default orientation but will not change your orientation to something else if you unlock... In short, having a promise here would be very hard to implement reliably, I don't think it is a good idea to require this.

(In reply to Mounir Lamouri from comment #5)

> We can't reliably know when the unlock is done given that it means that we
> lock to the default orientation which might be platform specific and the
> browser might not actually know it.

Hmm OK, that's kind of a shame, but seems like a good enough justification. Might be worth adding a non-normative explanatory note about this.

I believe this is now fixed. I have open an issue in the GH repository about the editorial change wrt to unlock() not returning a promise: https://github.com/w3c/screen-orientation/issues/31