Primer for PocketPrioritize

Until I have time to write proper documentation, this will serve to get beta-testers started with this product.

PocketPrioritize (PocPri) is a small utility permitting control of thread priorities and pseudo-control of process priorities.

This is an powerful application for advanced users only . Microsoft never intended user control of global process priorities on the PocketPC. Due to this, there is no official PocketPC API for most of this application's features. I made use of multiple undocumented APIs. Therefore, it may not operate properly, it may not operate at all, or it may even be harmful to the PocketPC. Therefore, the user must take complete responsibility for any repercussions caused by using PocketPrioritize.

See the PocketPrioritize product page for further details about this product including system requirements and devices with which PocPri has been tested successfully.

Documentation by Feature

• Interface
• Thread Menu
• Process Menu
  • Pseudo-Priority Adjustment (PPA)
  • Lock
  • Kill
• Action Menu
• Scan Processes
• Auto-Scan
• Exclusion List
• On Close
• Special note to Task Manager users

Interface

The majority of the PocPri interface is used by the Primary Listing. Processes are listed by their module name (which should be the name of the executable file) while Threads are listed, indented, by their Thread ID in hexadecimal (e.g. 0x313F11A9) directly under the process of which they are a part.

The second column for a thread row displays the current priority of that thread. The third column for a thread row displays the delta.

The second column for a process row remains empty. The third column for a process row displays the current Pseudo-Priority Adjustment for that process. This value is surrounded in square brackets [] if it is locked.

All features in PocPri are available through menus. The Action Menu is only available from the menu bar. The Process Menu and Thread Menu are available both from the menu bar and, contextually, when you select either a process or thread entry in the Primary Listing and "tap-and-hold".

Thread Menu

The Thread Menu, which may be invoked either from the menu bar or via "tap-and-hold" when a process is selected, contains all thread-level features.

The simplest and most direct functionality in PocPri is the adjustment of thread priorities, which is performed directly from the Thread Menu. You can select any priority Idle through Highest (I chose to leave Critical unavailable, although this may change after getting user comments). To use this feature, simply select a thread, invoke the Thread Menu, and select the desired priority.

Process Menu

The Process Menu, which may be invoked either from the menu bar or via "tap-and-hold" when a process is selected, contains all process-level features.

Process Menu - Pseudo-Priority Adjustment (PPA)

This is the core functionality of PocPri. This allows the user to adjust all threads of a process with a single command.

To use this feature, select a process, invoke the Process Menu, and select an adjustment. A positive value will increase the priority of all threads in that process by 1 or 2 levels, while a negative value with reduce the priority of all threads in that process by 1 or 2 levels. If a PPA is already set and a new one is applied, the adjustment is to the original value. (e.g. If the current PPA is set to +1, and a new PPA is set to -1, all threads in that process will be reduced in priority by two levels)

Unlike manually setting thread priorities, PPA will adjust thread priority past Highest to Critical. Beware of this as threads, other than certain system threads whose priority should never be changed, should not be set to this high a priority.

When PocPri is closed (not minimized), it will attempt to reset all PPAs to 0 first. This is to prevent the threads from being elevated again on the next execution of PocPri. Some programs, however, may terminate PocPri without warning and PocPri may not be able to make this adjustment in time. There is nothing that can be done about this from within PocPri. If you encounter an application that does this, request that the author of that application send a WM_CLOSE message to the main window of PocPri with a suitable delay before calling TerminateProcess().

Process Menu - Lock

To use this feature, select a process, invoke the Process Menu, and click on Lock to lock the PPA of that process. If the process is already Locked it will unlock it. A locked PPA is designated by square brackets around the PPA value (third column for process rows).

When a lock is enabled on a PPA, PocPri will remember that PPA from session to session. (e.g. If you set the PPA of a process to +1, then close PocPri or soft-reset the device, the next time PocPri is launched, it will automatically invoke the PPA of +1 for that process once it detects its presence.)

Be aware that if a PPA is locked for an application, and PocPri is terminated abruptly by another program (or, perish the thought, crashes) that it will not have a chance to reset the PPA of that application to 0 before exiting. Then, when PocPri is launched again, it will re-elevate (or re-depreciate) the priorties for that process again. As long as PocPri is closed normally, or terminated with sufficient warning from the other program, this will not occur.

Process Menu - Kill

To use this feature, select a process, invoke the Process Menu, and click Kill followed by the method of killing the other process. Currently, only TerminateProcess() is available. This sends no significant warning to the process being killed and must be used with extreme care.

Action Menu

The Action Menu, which may only be invoked from the menu bar, contains the core process/thread detection functions and several persistant settings.

Action Menu - Scan Processes

When launched, PocPri automatically performs Scan Processes. The user can manually initiate a new scan at any time using this function.

Scan Processes detects all running processes/threads and lists them in the Primary Listing. Until Scan Processes has been successfully performed, neither the Process Menu nor Thread Menu will be available.

Action Menu - Auto-Scan

When Auto-Scan is enabled, PocPri will perform a Scan Processes periodically at the interval selected. This is important so that PocPri can detect and apply locked PPAs on newly run processes.

There are four settings available. Off disables Auto-Scan, while 10s, 30s and 60s set the Auto-Scan interval to 10, 30 and 60 seconds, respectively.

Action Menu -Exclusion List

Windows Mobile devices run a large number of processes in the background, most of which should never be adjusted in any way. Additionally, along with their threads, these processes take up a massive amount of space in the Primary Listing making it difficult for the user to find and act on the processes (s)he wishes. The Exclusion List is a list of all modules (executable names) that should be omitted from the Primary Listing.

At this time, the Exclusion List is loaded from a text configuration file located in the same directory as the PocPri executable. This file must be named PocPriEx.txt. There is no facility, as of yet, within PocPri to edit this file. However, any text editor can be used to do so. At a later date I will consider including adding Exclusion List editing directly into PocPri.

PocPri ships with a default PocPriEx.txt filled with all the exclusions I use for my Windows Mobile 5 device. I will add new exclusions to the default file after getting input from beta testers.

Action Menu - On Close

This should currently remain set to Normal Behavior.

Setting this to Always Minimize will make PocPri unable to even try to close gracefully when an application like WisBar forces it closed, even though this is the opposite of the intended effect. Therefore, leave this set to Normal Behavior.

Setting this to Always Close will force PocPri to close itself (gracefully) when told to minimize by the operating system.

Special note to Task Manager users

When used with programs that replace the default minimize function of the top-right corner button with a close function, or otherwise close it, PocPri needs to be carefully observed if using the Lock function for the reasons explained in it's section. Generally, PocPri is designed to be run all the time and not closed. PPAs are reset to 0 when PocPri is (gracefully) closed. Therefore you should minimize PocPri instead of closing it unless you only use the thread priority function, which is not effected by closing PocPri.

It may depend on the speed of the device, but it appears that WisBar Advance 2 does give just enough warning to PocPri for it to close gracefully as long as On Close is set to Normal Behavior. We are talking milliseconds here, so I will have to wait for input from testers to determine if this is always the case. If it is not, it will be up to the task manager authors to implement a more gentle close mechanism as absolutely nothing can be done to PocPri to prevent it from being terminated abruptly, as this ability is integral to the operating system. To facilitate graceful closing, however, PocPri does attempt to close itself gracefully immediately if its main window receives a WM_CLOSE message.

I recommend to Task Manager authors that they implement two features to resolve this:

• Allow certain individual applications, such as PocPri, to be set by the user to "minimize only" instead of close while retaining the close functionality for all other applications.
• Send a WM_CLOSE to the main window of the program to be closed and then wait a user-definable number of milliseconds before attempting the TerminateProcess() (500-1000 ms would be a nice default). Unfortunately, it appeared, on my initial inspection, to be very difficult to determine the top window for an application due to what appears to be a bug in EnumWindows() on the Windows Mobile platform (where many windows of the same process are detected as top level). I will continue to investigate this and would appreciate input from anyone who has successfully written code for determining the top level window only.