Zamae

The Prosciutto Project

a small footprint mobile application engine and browser - and open source!

Links: Released under GPLv3 java.net member

CONFIGURATION

The configuration tag comes in handy for indicating *exactly* the amount of objects you are going to use in your application, and thus want Prosciutto to reserve memory for them up-front (upon initialisation).

All attributes - including the tag itself - are optional, but we strongly recommend that you specify your own settings, as the default values might not be the best fit for your application.

Here's how to populate the config tag. Note that the values are actually the default values as defined inside the engine, so it wouldn't take any effect to declare particularly those values in a config tag. Again, you should change the values for whatever better suits your application. 

    <config 
        language="1"                                        //default language. Can be set to 0 (english), 1 (spanish), or 2 (portuguese). Default if not specified is 0 (english).
        form_qty="10"                                       //form quantity. The amount of forms you want Prosciutto to reserve cache for.
        buttons_form="60"                                   //buttons per form. The maximum amount of buttons you expect to use in any given form.
        tpl_qty="10"                                        //template quantity. The amount of different templates you want Prosciutto to reserve cache for. Usually matches the amount of forms, as templates are only attached to forms.
        buttons_tpl="8"                                     //buttons per template. The amount of buttons you say you'll have (maximum) in any given template.
        timer_qty="8"                                       //timer quantity. The amount of different timer objects you expect to live in Prosciutto's lifecycle, at any given time. 
        font_qty="8"                                        //font quantity. How many different font objects will you define in your application?
        imgarray_qty="8"                                    //image arrays quantity. How many different image arrays objects do you want Prosciutto to set heap space apart for?
        images_per_array="8"                                //images per array quantity. In each image array object, how many actual images (maximum) will each contain, at any given time?
        msg_qty="100"                                       //message inbox capacity. Override this only if you are not using any object-to-object messaging by means of the API. Mostly used for "goback" actions internally; my recommendation is you can set it to the amount of "goto" actions you have in your app.
        colordef_qty="100"                                  //color definitions quantity. How many colors will you define for this apps' UI objects?. This is the amount that Prosciutto will reserve for you.
        wrapper_buttons="5"                                 //number of wrapper buttons you expect to use in your application.
        wrapper_lines="100"                                 //maximum number of wrapper lines each wrapper button will allow to split. If a button's text exceed this number in lines, exceeding lines will be discarded.
        lbs_timeout="60"                                    //this is only read by Prosciutto in the LBS supporting version. Indicates the timeout in seconds, for which Prosciutto will wait for the underlying platform to read the current location.
        debug_form="26000"                                  //if you are using debugging (only for developers), you can tell Prosciutto which form you will be using for showing debug information, so Prosciutto won't keep track of events when showing this specific form.
    />


EXAMPLE AND EXPLANATION - OPTIMISING MEMORY USAGE

The configuration we use per default in Prosciutto is as follows:
                                                                                      
     <config 
        form_qty="10" 
        buttons_form="60" 
        tpl_qty="10" 
        buttons_tpl="8" 
        timer_qty="8" 
        font_qty="8" 
        imgarray_qty="8" 
        images_per_array="8" 
        msg_qty="100" 
        colordef_qty="100"
     />
Actually, this is identical to the default values embedded with the engine, so commenting out this line or not declaring it all will have equal effects as to memory allocation.

Now, as we know the amount of buttons and forms we use, we can tweak those values and tell Prosciutto to only allocate space for the things we are going to use. Thinking of it, in the demo example (HelloProsciutto) the form that has the most buttons has some 10 buttons, so we can get the 60 default value to 10. Also, the amount of forms we cache at any time is default to 10, but as long as we don't need to keep that all in memory for some reason (like saving data entered by the user), we can definitely take it down to a minimum of 1. Let's say we only need half that much, 5. Templates are attached to forms, so we keep the maximum equal to the form value. As of timers, we are actually using only 1 timer (to show transition from the splash screen to the login screen), so why allocating 8? let's tell Prosciutto we only need 1 timer space. We can also know that we are using only up to 2 images per image array in our HelloProsciutto demo application (img array id 81001), so let's take that down to 2. Also we only have 2 img_aray objects defined, so let's take that down to 2 as well. Also we have the internal messaging engine, which defaults to save up to 100 messages at any given moment. As we are not defining any message apart from the ones that are of internal use of Prosciutto (such as the calling form so a button knows where to go in a "goback" action), let's make it just the half, 50. You can see we are just doing rough calculations, no rocket science. Colordefs can also be tweaked, if you look into model.xml we have 1, 2, 3.. 10 different color configurations. So why allocating 10 times 10? Same happens with Fonts. We only have 4 fonts defined, so let's take that value to 4. Let's see how this behaves when we tweak the config values: 
    <config 
        form_qty="5" 
        buttons_form="20" 
        tpl_qty="5" 
        buttons_tpl="8" 
        timer_qty="1" 
        font_qty="8" 
        imgarray_qty="8" 
        images_per_array="1" 
        msg_qty="50" 
        colordef_qty="10"
    />

Now I have prepared a memory usage graph to illustrate how this may impact in your application performance. This following graph shows the free memory when we run HelloProsciutto on Sun's WTK emulator with 2 MB of heap memory. The running sequence comprises of the following phases:

1) initialization
2) XML reading
3) displaying the splash form
4) transition to login form upon timer expiration, and
5) load and display the login form

Mem usage graph

The graph in blue shows the free memory when using the default values as defined in Prosciutto. In such a case we reserve memory upfront, so it's the way that we use the most of memory so Prosciutto can work safely throughout its lifecycle.

The graph in brown shows the free memory when we use the config tag by indicating the very same default values as defined in Prosciutto. In this case we gain something between 5 to 10kb of free memory, because we only do allocation for the objects that are found in the model.xml as we crawl through it. While it *could* lead to more memory fragmentation, Prosciutto takes care of that because it does memory allocation at that time and is cautious about asking for more memory while in execution (phases 3, 4, and 5, to phase n) or normal running lifecycle.

Now comes the interesting part. Take a look at the yellow graph. The yellow graph represents the amount of free memory at any phase of Prosciutto lifecycle, when you define the config tag with proper values chosen consciously. You can see there's a lot more free memory to play with! This memory is working memory, so you can use it for anything else you might need, for instance loading more images in your application, this making it richer :).

Finally, I have also run the same test on a Nokia Series 40 emulator to get something closer to real. The emulator is set to have a 512kb heap memory, which is what most series 40 handsets out there have available.
Mem usage graph - Nokia series 40 emu
Don't let you be disappointed by the memory slowly decreasing while through all the phases - you can see the free memory comes back all the way up to almost 250 kb in the end, to the right? That's because of how the series 40 garbage collector works. It has a lazy approach in the sense it will only free up as much memory as it can when it really requires to free memory. Otherwise it just passes and continues to give control to the application, for obvious performance reasons.

One more, this is how the Motorola L6 SDK behaves with the same application and the same scenarios. This is with an L6/L7 emulator, with reportedly 819200 bytes heap size (actually only near 556k are available to the application).
Mem usage graph - Nokia series 40 emu

Conclusion: have fun writing rich and optimized applications! :)

Back to UI objects listing