locked
suspension (ie, checkpoint) event

    Question

  • Hello guys.

    quick question: I've noticed that the we've got 2 events which are fired when an app is suspended: WinJS.Application's checkpoint and WebUIApplication's suspending.

    Can anyone tell me the difference between them? I can see some differences. for instance,  long operations initiated from within checkpoint must set a promise that is signaled when it completes and suspending resorts to deferrals...

    is there any guidelines on when to use one or the other? does it matter?


    Luis Abreu

    Friday, May 25, 2012 9:42 PM

Answers

  • WinJS.Application.oncheckpoint is a wrapper for WebUIApplication.onsuspending. To take a step back, WinJS.Application coalesces events from a number of sources into a single source, specifically where it can add some value and/or simplification in doing so.

    With checkpoint, WinJS specifically saves anything you put in the WinJS.Application.sessionState object (just does JSON.stringify and saves to a file in local appdata, and it does this after your checkpoint handler has completed). This ties into the WinJS.Application activation process, where it will reload that sessionState object for the previousExecutionState==terminated case.

    The args.setPromise method that you get inside checkpoint is itself a wrapper around the deferral mechanism that WebUIApplication provides--same purpose, different interface. The purpose behind this is that Windows will be free to suspend your app once you return from the WebUIApplication.onsuspending handler, unless you ask for a deferral. You do this if you need to kick off an async operation when suspending, so you ask for a deferral and call it's complete method in your async operations completed handler.

    In raw form, this means that you need to save the deferral object from the suspending handler into some variable that your async operation's completed hander can see.

    What WinJS does is automatically ask for a deferral itself, which it holds onto and wraps inside the setPromise method. This means that you can just say args.setPromise(myAsyncOp()), and setPromise will call the promise's done method and then call the deferral's complete when that promise completes.

    Bottom line: you can use either. Think of checkpoint as an re-interpretation of suspending.

    Remember that stuff like this in WinJS is a library of useful functionality and not a requirement. It's just very compelling functionality, because the WinJS team only implemented stuff that most apps would have to do and where there was clear value in doing so. (This is why WinJS.Application doesn't have its own resuming event, because it doesn't add value for it.)

    .Kraig

    P.S. Do note that the deferral mechanism is just for async handling so you can return from suspending/checkpoint and not block the UI thread. Asking for a deferral will not give you extended time before being suspending (i.e. you always get 5 seconds).

    Saturday, May 26, 2012 3:59 AM
  • Almost--if you load WinJS, the sessionState object will always be saved whether or not you handle checkpoint yourself. WinJS has its own handler for checkpoint in which it does the save, so you can write properties to sessionState anywhere in your app and trust that they will be saved automatically without any other action on your part.

    If you have something to add to sessionState in your own checkpoint handler, WinJS makes sure that one is called before its own checkpoint handler, so you can again trust that those values will be saved.

    Saturday, May 26, 2012 2:26 PM

All replies

  • WinJS.Application.oncheckpoint is a wrapper for WebUIApplication.onsuspending. To take a step back, WinJS.Application coalesces events from a number of sources into a single source, specifically where it can add some value and/or simplification in doing so.

    With checkpoint, WinJS specifically saves anything you put in the WinJS.Application.sessionState object (just does JSON.stringify and saves to a file in local appdata, and it does this after your checkpoint handler has completed). This ties into the WinJS.Application activation process, where it will reload that sessionState object for the previousExecutionState==terminated case.

    The args.setPromise method that you get inside checkpoint is itself a wrapper around the deferral mechanism that WebUIApplication provides--same purpose, different interface. The purpose behind this is that Windows will be free to suspend your app once you return from the WebUIApplication.onsuspending handler, unless you ask for a deferral. You do this if you need to kick off an async operation when suspending, so you ask for a deferral and call it's complete method in your async operations completed handler.

    In raw form, this means that you need to save the deferral object from the suspending handler into some variable that your async operation's completed hander can see.

    What WinJS does is automatically ask for a deferral itself, which it holds onto and wraps inside the setPromise method. This means that you can just say args.setPromise(myAsyncOp()), and setPromise will call the promise's done method and then call the deferral's complete when that promise completes.

    Bottom line: you can use either. Think of checkpoint as an re-interpretation of suspending.

    Remember that stuff like this in WinJS is a library of useful functionality and not a requirement. It's just very compelling functionality, because the WinJS team only implemented stuff that most apps would have to do and where there was clear value in doing so. (This is why WinJS.Application doesn't have its own resuming event, because it doesn't add value for it.)

    .Kraig

    P.S. Do note that the deferral mechanism is just for async handling so you can return from suspending/checkpoint and not block the UI thread. Asking for a deferral will not give you extended time before being suspending (i.e. you always get 5 seconds).

    Saturday, May 26, 2012 3:59 AM
  • Hello Kraig.

    Thanks for the taking the time to explain what's going on :)

    If I understood what you said, then there is, in fact, one difference between them: the session state object is only persisted when you handle the WinJS.Application.checkpoint, right? in other words, if I decide to go with the suspending event, then I'll have to take care of persisting the necessary data for reactivation. am I right?

    Luis Abreu

    Saturday, May 26, 2012 9:12 AM
  • Almost--if you load WinJS, the sessionState object will always be saved whether or not you handle checkpoint yourself. WinJS has its own handler for checkpoint in which it does the save, so you can write properties to sessionState anywhere in your app and trust that they will be saved automatically without any other action on your part.

    If you have something to add to sessionState in your own checkpoint handler, WinJS makes sure that one is called before its own checkpoint handler, so you can again trust that those values will be saved.

    Saturday, May 26, 2012 2:26 PM
  • Thanks again Kraig.



    Luis Abreu

    Saturday, May 26, 2012 9:05 PM