Sun Microsystems 2 manual

Sun Microsystems, Inc. www .sun.com Multitasking Guide Sun J av a™ Wireless Client Software, V ersion 2.0 J av a Platf or m, Micro Edition May 2007[...]

Copyright © 2007 Sun Microsystems, Inc., 4150 Network Cir cle, Santa Clara, California 95054, U.S.A. All rights reserved. Sun Microsystems, Inc. has intellectual pr operty rights relating to technology embodied in the pr oduct that is described in this document. In particular , and without limitation, these intellectual property rights may include[...]

iii Contents Preface ix 1. Introduction 1 Multitasking 2 Robustness 3 Mechanisms Compared With Policies 3 2. Multitasking Safety 5 Multitask Safety and Multithread Safety 6 Global and Static Data 7 Singletons 8 Multitasking Safety Example 9 Multithread Safety 1 1 Multitask Safety 13 Establishing Per-T ask Context 15 3. Managing Native Resources 21 [...]

iv Multitasking Guide • May 2007 Default Resource Allocation Policies 24 Customization of Resource Allocation Policies 25 4. Other Multitasking Issues 29 Switching the Foreground MIDlet 29 Default Policy 30 Alternative Policies and Their Implementations 30 Scheduling the CPU 30 Default CPU Scheduling Policy 31 Alternative Policies and Their Imple[...]

v Code Samples CODE EXAMPLE 2-1 Native API for a Microwave Oven 9 CODE EXAMPLE 2-2 Typical usage of the microwave 10 CODE EXAMPLE 2-3 Simple Java API for the Microwave Oven 10 CODE EXAMPLE 2-4 Introducing a Locking Mechanism for Thread Safety 11 CODE EXAMPLE 2-5 Using the Locking Mechanism 12 CODE EXAMPLE 2-6 Migrating the Initialization Variable t[...]

vi Multitasking Guide • May 2007[...]

vii T ables T ABLE 3-1 Constant Definitions for the Resource Management Policy 26[...]

viii Multitasking Guide • May 2007[...]

ix Pr eface The Multitasking Guide highlights multitasking programming issues in the Sun Java™ W ireless Client softwar e. It describes how to make code safe for the multitasking environment of the Java W ireless Client softwar e. There is a special section about resour ce management. The Multitasking Guide also describes some multitasking polici[...]

x Multitasking Guide • May 2007 Note – Note - Sun is not responsible for the availability of web sites mentioned in this document. Sun does not endorse and is not responsible or liable for any content, advertising, products, or other materials available through such sites. How This Guide Is Or ganized This book contains the following chapters: [...]

Preface xi T ypographic Conventions Used in This Guide Multitasking T est T ools Multitasking Quality T est Suite Guide V iewing reference documentation cr eated by the Javadoc™ tool Java API Reference V iewing reference documentation cr eated by the Doxygen tool Native API Reference T ypeface Meaning Examples Courier AaBbCc123 The names of comma[...]

xii Multitasking Guide • May 2007 Accessing Sun Documentation Online The Java Developer Connection™ program web site enables you to access Java platform technical documentation at http://java.sun.com/ . Sun W elcomes Y our Comments W e are interested in impr oving our documentation and welcome your comments and suggestions. Provide feedback to [...]

1 CHAPTER 1 Intr oduction Customers use mobile phones and other handheld devices for many tasks, such as making phone calls, taking photographs, playing games, organizing contact information, keeping a calendar of events, and accessing web sites. It is natural for them to want to do more than one of these tasks at a time. For example, a customer mi[...]

2 Multitasking Guide • May 2007 Multitasking The Connected Limited Device Configuration HotSpot™ Implementation can run multiple Java applications within a single operating system (OS) process. Historically , a CLDC virtual machine (VM) could run one Java application at a time, and each virtual machine typically required its own OS pr ocess. Ru[...]

Chapter 1 Introduction 3 Robustness In addition to providing the multitasking that users want, tasks have the following benefits: ■ Fault containment - If a Java application crashes, then any problems caused by this crash are limited to the task. Applications running in other tasks are unaffected. ■ Clean termination - When a Java application e[...]

4 Multitasking Guide • May 2007 Because policies are so device dependent, this book does not recommend specif ic policy combinations. As you determine the policies for your device, keep in mind that policies interact with each other and not all combinations of policies make sense. For example, if you have a policy to allow a MIDlet to access a so[...]

5 CHAPTER 2 Multitasking Safety The Java W ireless Client softwar e provides the ability to r un multiple MIDlets concurrently in a single OS process. Fr om the standpoint of the OS, there is one process and one Java virtual machine. However , fr om the standpoint of a Java application, it appears as if it is running in its own, independent virtual[...]

6 Multitasking Guide • May 2007 The following list summarizes the multitasking safety issues to consider when you update or add native code for your port: ■ Multitask safety and multithread safety ■ Native global or static data ■ Singletons Multitask Safety and Multithr ead Safety Many systems today are multithreaded , which r equires code [...]

Chapter 2 Multitasking Safety 7 For example, certain native functions (such as file storage) must be maintained on a per-application basis. In a single-tasking system, only one application is running, and so all file access is on behalf of that one application. In a multitasking system, several applications are running, and so the f ile access code[...]

8 Multitasking Guide • May 2007 Maintain the following invariants: ■ A value of zero means a NULL pointer ■ A nonzero value means a valid native pointer In native code, when you allocate memory , use KNI field access to store the pointer in the private field. When you fr ee the native memory , use KNI field access to store 0 in the field. Usi[...]

Chapter 2 Multitasking Safety 9 Y ou might find that you cannot organize the singleton’s maintenance in this way , because its state must be updated synchronously and atomically . Maintaining the foregr ound state is an example of this type of singleton. In this case, migrate a key piece of state into native memory and handle updates through call[...]

10 Multitasking Guide • May 2007 */ extern void mw_cook(MWCB callback, void *context); T ypical usage of this API is shown in CODE EXAMPLE 2-2 . CODE EXAMPLE 2-2 T ypical usage of the microwave void cb_popcorn(MWSTATUS status, void *context) { if (status == MW_INTERRUPTED) { /* tell the user that the popcorn isn't finished */ } else { ... } [...]

Chapter 2 Multitasking Safety 11 Multithr ead Safety The most obvious problem with the interface defined in CODE EXAMPLE 2-3 is that it is not thread-safe. A single Java platform thr ead (Java thread) calling the APIs can certainly use it effectively , but if another thread attempts to use the API, things almost certainly break. For example, one th[...]

12 Multitasking Guide • May 2007 public static synchronized setPower(int power) { if (owner != Thread.currentThread()) { throw new IllegalStateException(); } n_setPower(power); } public static synchronized setTime(int nsecs) { if (owner != Thread.currentThread()) { throw new IllegalStateException(); } n_setTime(nsecs); } public static synchronize[...]

Chapter 2 Multitasking Safety 13 This API is now multithread safe. However , it is not multitask safe. The reason is that the thread safety pr operties are achieved using mechanisms that belong to the Microwave class. These include static variables ( initialized , owner ) of the Microwave class. Thread synchr onization and wait and notify operation[...]

14 Multitasking Guide • May 2007 CODE EXAMPLE 2-6 Migrating the Initialization V ariable to Native Code (Doesn’t W ork) // Microwave.java static native boolean getInitState(); static native void setInitState(boolean init); public static synchronized void lock() throws InterruptedException { ... if (!getInitState()) { init(); setInitState(true);[...]

Chapter 2 Multitasking Safety 15 { if (initialized == 0) { initialized = 1; mw_init(); } KNI_ReturnVoid(); } Note that no mutual exclusion is necessary in native methods. The CLDC HotSpot Implementation has a single thread that runs all Java thr eads and all native methods. This thread can run at most one native method at a time. The system cannot [...]

16 Multitasking Guide • May 2007 The lock() and unlock() static methods were added to the Microwave class to protect the context that was being built implicitly in library static data by the setTime() and setPower() methods. This locking protocol ef fectively provides mutual exclusion around library static data. This works in a single-tasking env[...]

Chapter 2 Multitasking Safety 17 For the sake of simplicity , ignore the situation where another cooking operation might already be in pr ogress, and ignore the logic for block and unblocking the calling thread. Note also the use of a technique for allocating a native context object and storing its pointer in a Java object field. All data used in t[...]

18 Multitasking Guide • May 2007 } else { /* this is a reinvocation after having been awakened */ statusp = (MWSTATUS *)KNI_GetIntField(thisObj, nativePtrFieldID); retval = (int)(*statusp); KNI_SetIntField(thisObj, nativePtrFieldID, 0); free(statusp); } KNI_EndHandles(); KNI_ReturnInt(retval); } void callback(MWstatus status, void *context) { MWS[...]

Chapter 2 Multitasking Safety 19 These examples show how multitask safety can be achieved by judicious migration of data from Java code into native code (for global singletons) and from native code into Java code (for context-specific data). Some libraries have explicit context objects, with all operations relative to that context object. For cases[...]

20 Multitasking Guide • May 2007[...]

21 CHAPTER 3 Managing Native Resour ces The typical device is constrained in the amount of resources, such as memory or sockets, that it has available. When the Java W ireless Client software is r unning on a device, it is often provided with a fixed set of r esources that it cannot exceed. In a single-tasking environment, a single MIDlet has acces[...]

22 Multitasking Guide • May 2007 The Java W ireless Client softwar e solves this problem by pr oviding a set of resource management mechanisms that can be used to control how resour ces are allocated. The Java W ireless Client software also pr ovides a set of resource management policies that determine how the system behaves under certain conditi[...]

Chapter 3 Managing Native Resources 23 Many MIDlets are not designed to deal with failure in the midst of an operation. If such a MIDlet is updating one of its date structures when an allocation failur e occurs, the date structure might end up in an inconsistent or corrupted state. Providing MIDlets with a r esource r eservation will prevent failur[...]

24 Multitasking Guide • May 2007 Revocation The revocation mechanism lets the system take a resour ce from one MIDlet to give the resour ce to another MIDlet. This second MIDlet is sometimes said to have preempted the r esource from the f irst MIDlet. Resources ar e revoked without receiving any r equest from the MIDlet. The MIDlet might or might[...]

Chapter 3 Managing Native Resources 25 behavior might be less confusing to the user than the failures that could happen with the open resour ce policy , because these failures are pr edictable. They always happen when the user tries to start the application. The default policy is open for competition. T o use a fixed-partition resource policy , you[...]

26 Multitasking Guide • May 2007 Each resour ce typically has five constants that define the policy . A pair of constants defines the r eservation and the limit for each MIDlet suite. These constants have the suff ixes SUITE_RESERVED and SUITE_LIMIT , respectively . Another pair of constants defines the r eservation and limit for the AMS task. Th[...]

Chapter 3 Managing Native Resources 27[...]

28 Multitasking Guide • May 2007[...]

29 CHAPTER 4 Other Multitasking Issues Multitasking raises some issues related to the behavior of the Java W ir eless Client software. This chapter describes the issues, how they are handled by the Java W ireless Client softwar e, and possible alternatives. Most of the issues discussed in this chapter relate to the implementation of the Java platfo[...]

30 Multitasking Guide • May 2007 Default Policy The Java W ireless Client software supplies a default policy for how a MIDlet gains the foregr ound. It enables the user to switch to an application list screen at any time by pressing a hot key . By default, the hot key is the Home key found on many platforms. The application list screen shows a li[...]

Chapter 4 Other Multitasking Issues 31 Default CPU Scheduling Policy By default, the Java W ireless Client softwar e permits background applications to have some CPU time. A background application can also interrupt the foregr ound application under some circumstances. Specifically , the CPU scheduling policy is fair share, which gives a higher pro[...]

32 Multitasking Guide • May 2007 Interrupting the User Although a good user interface permits a user to interrupt applications at any time, it does not do the same to the user . Instead, it interrupts the user only when necessary . Unnecessary feedback, confirmation messages, and error messages that requir e a user response are distracting. See t[...]

Glossary 33 Glossary API Application Programming Interface. A set of classes used by pr ogrammers to write applications, which provide standar d methods and interfaces and eliminate the need for programmers to r einvent commonly used code. AMS Application Management Service. The system functionality that completes tasks such as installing applicati[...]

34 Multitasking Guide • May 2007 GCF Generic Connection Framework. A part of CLDC, it improves network connectivity for wireless devices. Home screen The main screen of the application manager . This is the screen the user sees after they exit an application. HTTP HyperT ext T ransfer Pr otocol. The most commonly used Internet protocol, based on [...]

Glossary 35 LCDUI Liquid Crystal Display User Interface. A user interface toolkit for interacting with LCD screens in small devices. Mor e generally , a shorthand way of referring to the MIDP user interface APIs. MIDlet An application written for MIDP . MIDlet suite A way of packaging one or more midlets for easy distribution and use. Each MIDlet s[...]

36 Multitasking Guide • May 2007 RMS Record Management System. A simple r ecord-oriented database that enables a MIDlet to persistently store information and r etrieve it later . MIDlets can also use the RMS to share data. SMS Short Message Service. A protocol allowing transmission of short text-based messages over a wireless network. SOAP Simple[...]

37 Index C CPU scheduling, 30 D data global, 7 static, 7 F foregr ound MIDlet switching, 29 L limit, 23 M mechanisms compared with policies, 3 multitask safety, 13 multitasking, 2 multitasking safety, 5, 6 multithread safety, 6, 1 1 N native concurrency, 7 native resour ces, 2 1 P policies compared with mechanisms, 3 R reservation, 22 resour ce all[...]

38 Multitasking Guide • May 2007[...]