thoughts on coding

February 8, 2013

WinJS.Promises – lessons learned

Filed under: Javascript, Windows8, WinJS, WWA — Tags: , — Frantisek @ 9:22 pm

WinJS.Promises – lessons learned

Goal of the promise is to bring the asynchronous programming into JS. It’s not new thing. You can find many information on wikipedia.

WinJS comes with built-in support of Promises. You can find more info on MSDN here.

Usage scenarios

  1. You call a native API which can take a long time. The call is started on UI thread. If it would take longer than 50ms and execute completely on UI thread, the user experience would be bad. The solution is to switch the execution to the background thread and later continue the work back on UI thread. In other words, API returns a promise object promising us that it will completed sometime later.
    var openPicker = new Windows.Storage.Pickers.FileOpenPicker();
    openPicker
        .pickSingleFileAsync()
        .then(function (file) {
            // do something with file
        });
    
  2. Splitting the work which runs on UI thread into several small chunks so the UI thread is not blocked. The result is that the whole execution time is longer but the application is more fluid, the UI thread is not blocked. It’s implemented via a call to setImmediate. This is very much used inside WinJS
  3. You build a library with a flexible API accepting an input which is not in your control. To make the API more robust, be prepared for longer data loading. In that case it’s recommended to use Promise and the consumer of that API can provide synchronous (fast case, 50ms) promise.

WinJS team did a great work and implemented built-in support of Promises for us.

In this article I’d like to summarize my personal experience with Promises, after using them for more than 1 year.

They have a state

They are built on the state machine. This means the promise has its internal state (i.e. created, working, completed, canceled ,error) and the methods which moves the state machine from state A to B. It’s good to keep it in mind, especially when you combine promises, i.e. chaining, joining promises, waiting for any promise.

Creating a promise

There are several ways how to do it:

  1. WinJS.Promise.wrap(value): it creates a completed promise with the result: value.
  2. WinJS.Promise.as(value): it checks if the value is promise and then returns it. Otherwise it’s same as WinJS.Promise.wrap(value). I use mainly this option.
  3. Calling new WinJS.Promise(completed, error, progress). The parameters are functions and none of them is required. If the promise is created, WinJS tries to complete it directly. If the promise is added to the chain (so other promises are in the chain before the created one) then the functions completed/error are called based on the previous promise result. Huh, starting to be complex, right? Yeap, but quite powerful.
    var promise = new WinJS.Promise(function(complete, error, progress) {
        setTimeout(function() {
            // do some work
            complete(sum);
        }, 1000);
    });
    

Chaining the promises

It’s possible to chain the promises:

var promise = WinJS.Promise.timeout(1000)
    .then(function() {
        //do some work
    })
    .then(function() {
        //do some work
    })
    .then(null, function(error) {
        //error handler
    });

This means that when the first promise finishes, the next promise in the chain is executed.

Returning a value from promises

Any value returned from the promise is translated back into the completed promise with the return value.

var promise = WinJS.Promise.timeout(1000)
    .then(function() {
        return 1 + 1;
    })
    .then(function(sum) {
        console.log(sum); // prints 2
    })
    .then(null, function(error) {
        //error handler
    });

Postponing the work, timeout-ing

Javascript developers are very used to use two ways how to postpone the work:

  1. msSetImmediate(function)
  2. setTimeout(function, milliseconds)

WinJS.Promises has the equivalent via calling one method: WinJS.Promises.timeout(milliseconds). If milliseconds are omitted or equal to 0, then msSetImmediate is used, otherwise setTimeout.

This is very useful technique when it’s necessary to execute CPU sensitive task while keeping UI responsive. It’s necessary to split the long CPU sensitive tasks into chunks and chain them with several timeouts (WinJS.Promise.timeout())

WinJS.Promise.as()
.then(function () {
    // do some work (part #1)
    return WinJS.Promises.timeout();
})
.then(function () {
    // do some work (part #2)
    return WinJS.Promises.timeout();
})
.then(function () {
    // do some work (part #X)
})
.done();

When timeout() is called, UI thread is able to process other tasks waiting in UI thread queue (i.e. user’s clicks, etc) and it keeps UI responsive.

Cancelling the promise

var p = WinJS.Promise.timeout(1000)
    .then(function () {
        return 1 + 1;
    })
    .then(function (sum) {
        console.log("Sum is " + sum);
    })
    .then(null, function (error) {
        //error handler
    });

console.log("Cancelling the promise");
p.cancel(); 

After call to cancel the promise, the promise finishes the current execution but stops the further promises in the chain execution. In the above example, “sum is 2” is not printed.

Failing the promise

There are several possible ways how to fail the promise:

  1. Returning the wrapped error promise
    var p = new WinJS.Promise.wrap(10)
        .then(function () {
            return WinJS.Promise.wrapError("error promise");
        }).then(null, function (error) {
            console.log("Promise error " + error + " occured but was handled");
        });
    
  2. Throwing the exception
    var p = new WinJS.Promise.wrap(10)
        .then(function () {
            throw "custom exception";
        }).then(null, function (error) {
            console.log("Promise error " + error + " occured but was handled");
        });
    
  3. Calling error callback
    var promise = new WinJS.Promise(function (complete, error, progress) {
        if (shouldComplete) {
            complete();
        } else {
            error("failing it");
        }
    });
    

Failing the promise has the following consequences:

  • when it’s the first level promise (it’s not nested promise done via join/any call), then failing the promise raises WinJS.Application.error event which by default terminates the application.
  • the failed promise is in the error state, its returned value is null
  • can be used to manage the execution flow in aggregating the promises via join/any (see bellow)

Aggregating the promises

It’s possible to create an aggregated promise which will continue when all promises (in case of join) or at least one of the promises (in case of any) are completed.

WinJS.Promise.join

There are two possible ways of passing the promises:

  1. Join the promises defined as object fields.
    var promises = {
        p1: new WinJS.Promise.wrap(1),
        p2: new WinJS.Promise.wrap(2),
        p3: new WinJS.Promise.wrap(3),
    };
    
    WinJS.Promise.join(promises).then(function (args) {
        console.log("p1: " + args.p1); // writes 1
        console.log("p2: " + args.p2); // writes 2
        console.log("p3: " + args.p3); // writes 3
    });
    
  2. Join the promises defined as an array of the promises
    var promises = [new WinJS.Promise.wrap(1), new WinJS.Promise.wrap(2), new WinJS.Promise.wrap(3)];
    
    WinJS.Promise.join(promises).then(function (args) {
        console.log("0. promise: " + args[0]); // writes 1
        console.log("1. promise: " + args[1]); // writes 2
        console.log("2. promise: " + args[2]); // writes 3
    });
    

As you can see above, the completed result of the joining promise is the input object/array with completed promises.

WinJS.Promise.any

There is also a second type of aggregated promise called “any” promise and it continues the execution when any of the input promises (object properties or array) are completed.

Managing the execution flow, passing the values

It’s possible to pass values using closure or using WinJS.Promise.join and passing the object with properties which contains promises or values. Let’s see it in action.

Example #1

Let’s say we are copying files (imagine promises p1, p2) and after all files were copied we want to check what was copied successfully. In the next sample p1 simulates first file failed, but we handled it. P1 result will be null, promise will be completed.

var p1 = new WinJS.Promise.as()
    .then(function () {
        console.log("Copying file P1");
        throw "custom exception #1";
    }).then(function (value) {
        console.log("P1 done");
        return value;
    }, function () {
        //log error, cleanup if required
    });
var p2 = new WinJS.Promise.as()
    .then(function () {
        // copy file 
        console.log("Copying file P2");
        return {}; // simulating a handle object
    }).then(function (value) {
        console.log("P2 done");
        return value;
    }, function () {
        //log error, cleanup if required
    });

WinJS.Promise.join({ 
     p1: p1, 
     p2: p2, 
     m3: 3})
.then(function (args) {
    //args.p1 = null
    //args.p2 = promise with handle to file
    //args.m3 = 3
    console.log("Joined promise completed");
}, function (error) {
    console.log("Joined promise error '" + error + "' occured but was handled");
}).done();

//output:
Copying file P1
Copying file P2
P2 done
Joined promise completed

Example #2

Let’s say we are copying files (imagine promises p1, p2) and after that we want to continue if ALL of the files are copied completely. In the next sample p1 simulates that copying first file failed so the whole promise failed. This means also joining failed.

var p1 = new WinJS.Promise.as()
    .then(function () {
        console.log("Copying file P1");
        throw "custom exception #1";
    }).then(function (value) {
        console.log("P1 done");
        return value;
    });
var p2 = new WinJS.Promise.as()
    .then(function () {
        // copy file 
        console.log("Copying file P2");
        return {}; // simulating a handle object
    }).then(function (value) {
        console.log("P2 done");
        return value;
    });

WinJS.Promise.join({ 
     p1: p1, 
     p2: p2, 
     m3: 3})
.then(function (args) {
    //args.p1 = null
    //args.p2 = promise with handle to file
    //args.m3 = 3
    console.log("Joined promise completed");
}, function (error) {
    console.log("Joined promise error '" + error.p1 + "' occured but was handled");
}).done();

//output:
Copying file P1
Copying file P2
P2 done
Joined promise error 'custom exception #1' occured but was handled

Notes:

  • inner promises (p1, p2) are left to fail
  • error object contains failed promises with error description

Logging the failed promises

It’s possible to get notified when any promise failed via attaching the listener to “error” event exposed on WinJS.Promise class.


function handlePromiseError(error) {
    console.log("PROMISE ERROR OCCURED " + (error.detail.exception ? error.detail.exception : ""));
};

WinJS.Promise.addEventListener("error", handlePromiseError);

Finishing the promises UPDATE!

Promise chain can end with .then() or .done() call. But there is a difference. Based on the official documentation http://msdn.microsoft.com/en-us/library/windows/apps/hh700337.aspx the difference is that when the promise failed finishes with

  • .then() – then the error is raised on WinJS.Promise.error and that’s all. The error is silently captured
  • .done() – then the error is raised on WinJS.Promise.error and then there is a code
                    setImmediate(function () {
                        throw value;
                    });
    

    which raises general application exception raised via WinJS.Application.error.

That’s clear. But the default promise usage/error handling within WinJS application is little bit different. When the application is started, call to WinJS.Application.start(), there is a default promise error handler attached to WinJS.Promise.error. This handler raises WinJS.Application.error when the failed promise doesn’t have parent promise.

There is also a default error handler attached to WinJS.Application.error which when called terminates the application by default.

Result of .done()/.then()

When you create WinJS application project and copy the samples from above MSDN link to your project, you find out, that the samples don’t work as described. The failed promises (both ending with then or done) terminates the application.

Reason: failed promise raises WinJS.Promise.error event which is by default handled and in case the failed promise doesn’t have any parent, WinJS.Application.error event is raised. Its event handler terminates the application.

Anyway, lessons learned: In general the best practice both for behavior and code readability is to use .done wherever you can and use .then wherever you have to.

Writing the promise to be readable

Chaining the promises can become very unreadable. My lessons learned are:

  1. You are chaining the promises and you want to return value. Don’t wrap value into the promise, return just the value. It gets automaticaly wrapped into the promise
  2. Don’t create inner chain the promises when not required and just chain them on the upper level

Bad style

	
p.then(function () {
    return asyncWork().then(function (result) {
        return moreWork().then(function (anotherResult) {
            return finishWork();
        });
    });
});

Good style

var p = WinJS.Promise.as();
p.then(function () {
    return asyncWork();
}).then(function (result) {
    return moreWork();
}).done(function (anotherResult) {
    return finishWork();
});

Chatching errors

Errors raised from the asynchronous code written using promises are hard to catch because the callstack doesn’t reflect where the error occurred but where how it was propagated in WinJS.Promise state machine. The recommended approach it turning on immediate catching JavaScript Runtime Exception in Visual Studio->Tools->Exception settings.

WinJS.Promise.as()
.then(function () {
    throw "custom exception";
}).done();

Callstack:
>	terminateAppHandler [base.js] Line 6928	Script
 	Application_errorHandler [base.js] Line 7097	Script
 	dispatchOne [base.js] Line 6998	Script
 	dispatchEvent [base.js] Line 6998	Script
 	drainQueue [base.js] Line 7038	Script
 	queueEvent [base.js] Line 7057	Script
 	Anonymous function [base.js] Line 7190	Script
 	Anonymous function [base.js] Line 7189	Script

Please note, there is no info where the exception actually occurred.

October 5, 2012

WinJS.UI.ListView and its LayoutNotInitialized exception

Filed under: Windows8, WWA — Tags: , — Frantisek @ 9:19 pm

While using WinJS.UI.ListView control and hiding/showing it together with binding/setting its datasource, it’s very possible to get the annoying exception “Layout is not initialized“.

Sample application

I developed a sampe app (after downloading just remove docx extension) where it’s possible to see when the exception is thrown.

The issue occurs in 2 cases:

  1. Given the ListView is hidden (display:none) and it is connected (via binding or JS) to empty list.
    When a new item is inserted into the datasource
    Then the ListView would like to render it but it’s necessary to measure the item size. Because of seeting “display:none” it is not possible, so mesureing fails and the exception is thrown
    Steps: check display none, click regenerate empty list, click add tile
  2. Given the ListView is hidden (display:none) and it is connected (via binding or JS) to non-empty list.
    When the items datasource is reset (via binding or JS) to some other non-empty datasource
    Then the ListView would like to render it but it’s necessary to measure the item size. Because of seeting “display:none” it is not possible, so mesureing fails and the exception is thrown
    Steps: check display none, click regenerate non-empty list

Solution

  1. using groupInfo property of layout which tells ListView: don’t measure on your own, here is the size
  2. when showing/hiding the listview we could enable/disable binding/setting the datasource

It’s possible to see both solution in the action in the downloaded application.

Summary

Solution a) is quite easy to do but it is not as performant as solution b.
Solution b) is better from the performance point of the view because when the listview is hidden and unbound, then it doesn’t receive and process any updates from datasource.

October 3, 2012

DataTemplate: solution to performance problems with WinJS Templates and binding

Filed under: Javascript, Windows8, WWA — Frantisek @ 9:32 pm

Problem: peformance issues with WinJS Templates and binding

WinJS Templates and Binding belongs to core parts of WinJS. Especially they fit very well into MVVM model, declarative binding, separation of concerns (UI logic contains really only UI logic)

Template rendering has the following high-level steps:

  1. optionaly create new container element which will contain a final rendered HTML – this step is optional because a result container can be passed as argument to the method)
  2. clone the template and append it into the container
  3. call WinJS.UI.processAll function on the root
  4. call WinJS.Binding.processAll function on the root and passed binding context objects (aka datacontext object)
  5. return the result

In addition, the whole process is wrapped into promises.

This process works quite well and you can achieve nice results with it. The problem starts when you try to finetune the performance. This is the slowest way of rendering item. There are several other ways which you can find in any WinJS docs/books.

WinJS Template and declarative binding is the slowest approach but the most flexible and I’d like to use it as often as possible but the performance has to be improved.

Let’s measure it!

Download MeasuringTemplatePerformance.zip and run the sample! (after downloading the file, remove extension docx, then unzip it) The sample I attached to this blog post is used to generate the color palette with the divs, using CSS3 grid layout. It does it in different ways and it measure the time spent.

Let’s review each solution.

Manual render

This is the fastest way and we will use it as our unit of measure. It’s the quickest way (at least for me) how to solve our problem. The only issue is that all UI logic (creating DOM elements, setting properties, etc) are done in codebehind, so there is NO separation of concerns.

Cloning render

It differs from manual process in the way how DOM elements are created – they are cloned form a template (do not mix it with WinJS template). In this case, the template is DOM element (acts as prototype) and we create cloned DOM element from the prototype and again, manualy set properties.
This is cca 3x slower than manual and still we violate separation of concerns.

Template, manual binding, manual placing in DOM

This approach uses WinJS template and its render method but it manually sets the properties (it doesnt use binding mechanism at all).
This is cca 7x slower than manual approach and again we violate separation of concerns.

Template, manual binding, auto placing in DOM

Similar approach as the previous case with just one difference: the result is directly added into DOM.
This is cca 11x slower then manual approach and again we violate separation of concerns.

Template, declarative binding, auto placing in DOM

This approach uses fully standard WinJS way of rendering, binding and adding the result to the DOM.
This is cca 30x slower than manual rendering but with full separation of concerns.

How to make the situation better?

The only solution is to reduce JS code to be executed. The source of the issue are two:

  1. calling WinJS.UI.processAll inside WinJS.Binding.Template.render – it could be totaly skipped as we don’t need to process any inner win controls.
  2. calling WinJS.Binding.processAll inside WinJS.Binding.Template.render – It could be rapidly enhanced. It’s overlook very often that WinJS.Binding.processAll has an optional argument called “bindingCache”. It is an object with specific interface and several usages:
    1. store all binding created during the binding process,
    2. cache parse all bindings found in the template
    3. stores all elements IDs with the bindings

Passing “bindingCache” can be reused for future binding process and it will speed up the binding process very much. Let’s see it in the action.

Template, cloning, declarative binding with binding cache, manual placing in DOM

This approach runs the binding process over the template element just to build the binding cache. Then for each data the template element is cloned and bound with support of binding cache. The difference is huge, IMHO.
This approach is slower only cca 4x than manual approach but follows separation of UI logic.

MvvmJS.UI.DataTemplate, declarative binding, auto placing in DOM

It is possible to go further and speed-up binding process with binding cache – binding process uses query selector to find all elements with data-win-bind attribute. I created a control, called MvvmJS.UI.DataTemplate which implements this logic and uses binding cache.

This approach is very simple and it’s slower only 3x than the manual approach but with full declarative binding and it wins for me. Especialy when the templates will be more complicated and it will be necessary to react on any data change.

Solution – MvvmJS.UI.DataTemplate

Usage of MvvmJS.UI.DataTemplate (UI/HTML part)

    <div id="dataTemplate">
        <div></div>
    </div>

Usage of MvvmJS.UI.DataTemplate (UI/code behind part)

                var cellTemplate = document.getElementById("dataTemplate");
                cellTemplate.winControl || WinJS.UI.processAll(cellTemplate);
                cells.forEach(function (cell) {
                    cellTemplate.winControl.render(cell, grid);
                });

DataTemplate class can be found in this project. MvvmJS project will be upgraded later (this month) with all new controls and logic.

June 20, 2012

Template Selector control

Filed under: Javascript, Windows8, WWA — Frantisek @ 7:56 am

MvvmJS control: TemplateSelector

WinJS enables the developers to use declarative programming in UI layer. It fits very well with MVVM architectural style. The main idea is that UI (view which is HMTL part) can be managed by the javascript object ( ViewModel ). All of this works automatically thankfully to data-binding.

Example: lets have a HTML element wich is “bound” to ViewModel (JS object). Changes done in ViewModel can be reflected on HTML element, i.e. it can change a style, color, change a text inside, etc. Full example can be checked here

The idea can be extended a level higher. The idea is taken from WPF/Silverlight world, especially from Caliburn (as I worked with it for more than a year).

MvvmJS.UI.TemplateSelector control

The goal of this control is simple: selects a template for the databinding context object and then renders it with that template.

The common usage scenario is: let’s have ListView which displays messages and each message has a type. Each type contains different properties and is handled and rendered differently. Solution is simple.

Code behind part

    var elm = document.body;

    var list = new WinJS.Binding.List();

    list.push({ type: 'call', duration: 100 });
    list.push({ type: 'text', text: 'Hello world!' });
    list.push({ type: 'call', duration: 300 });
    list.push({ type: 'call', duration: 200 });
    list.push({ type: 'text', text: 'WinJS is cool!' });

    WinJS.UI.processAll(elm).then(function () {
        return WinJS.Binding.processAll(elm, { messages: list });
    });
    

The above code creates list of the messages and each message has a type (call, text). Message types have different properties. After filling the list we process all win controls within the document.body and then we run databinding process over it.

Rendering part

    <div id="messageTemplate" data-win-control="WinJS.Binding.Template">
        <div class="message" data-win-control="MvvmJS.UI.TemplateSelector" 
            data-win-bind="winControl.model:self MvvmJS.Binding.wbind"
            data-win-options="{ selector: {
		                            type: MvvmJS.UI.TemplateSelector.PropertySelector,
		                            property: 'type',
		                            pattern: '/default.html#{0}',
	                            } }">
        </div>
    </div>
    <div data-templateid="call" data-win-control="WinJS.Binding.Template">
        <div class="call">Call, duration <span data-win-bind="innerText:duration"></span>s</div>
    </div>

    <div data-templateid="text"class="message text" data-win-control="WinJS.Binding.Template">
        <div class="text">Text message: <span data-win-bind="innerText:text"></span></div>
    </div>

    <div id="listView"
        data-win-control="WinJS.UI.ListView"
        data-win-bind="winControl.itemDataSource:messages.dataSource"
         data-win-options="{ itemTemplate: messageTemplate }">
    </div>
    

There is a listview which gets the messages as an input. The template used for the rendering refers to a template with template selector control. Template selector control gets the message as the input (setting property model) and renders it. Template selector selects the template based on the property (setting selector option to PropertySelector class) “type” of the input object (in this case a message).

Templating

The templates are located in the file default.html and are identified by data-templateid attribute. Template selector uses template loading mechanism with caching capabilities. The templates are identified by “#”. For the above example, in case message is of ‘call’ type, then the pattern ‘/default.html#{0}’ will be replaced to ‘/default.html#call’ which identifies the template with data-templateid attribute ‘call’ in the file ‘/default.html’. The recommended approach is to store the templates in the separate file, i.e. templates.html.

The result

Just another example

Another common situation is just having a general “alert” dialog which gets an object as the input. Based on the object type it’s possible to choose appropriate template to render the message, i.e. exception, business messages, etc. In the traditional scenario it’s necessary to write Javascript code with ifs or switch/case and manualy inject HTML into UI.

Summary

The above mentioned problems are very common and they have very similar solution which I isolated into a control. The control is under development and there will be several enhancements added, i.e. animations. The complete example can be found on http://mvvmjs.codeplex.com/

Create a free website or blog at WordPress.com.