Otherware

home *** CD-ROM | disk | FTP | other *** search

/ Otherware / Otherware_1_SB_Development.iso / amiga / system / jm1.lzh / jm / Docs / JM.doc next >

Wrap

Text File | 1992-04-05 | 56.3 KB | 1,717 lines

JM Users's Guide A Task Management System for the Amiga Version 1.1 (Copyright) 1992 Steve Koren April 4, 1992 Table of Contents Introduction to JM........................................3 Installing JM.............................................4 Copyright and Distribution Conditions.....................6 JM Passive Reporting Modes................................7 General System Status.....................................7 Process Status............................................8 Uptime....................................................10 Detailed Task Information.................................11 JM Active Management Modes................................12 Changing Running Task Priorities..........................12 Invoking Task Watch.......................................12 Task Logging..............................................13 CPU Bound Task Management.................................14 Starting Managed Jobs Which Require Interaction...........16 Changing the Weight of Running Managed Tasks..............17 JM Customization and Configuration........................18 The .jmrc Config File.....................................18 Other Options.............................................20 Technical Information and Theory..........................21 Bugs, Caveats, Disclaimers................................22 Future Enhancements.......................................25 Credits and Acknowledgments...............................26 JM Job Management Page 2 Users's Guide Introduction to JM JM is a job management system for the Amiga. It requires AmigaDos 2.04 or later. JM is designed for 68030/40 based machines, but versions are provided for 68000/20 systems. JM (Job Manager) is a tool which extends the AmigaDos multitasking environment. It can act in a passive, reporting mode: * JM can monitor CPU use, and report the total CPU time and CPU% for each task in the system. This is actual CPU time, accurate to 1/60 sec., not a guess based on task switching counts. * JM can monitor and report the invocation time of each task. * JM can monitor and report the system load average, time since boot, used CPU time, idle CPU time, the # of tasks started and finished, and idle CPU percentage. It can also play an active roll: * JM can allocate CPU cycles in any ratio to multiple CPU bound processes, something not before possible on the Amiga. (If you don't know whether you need this feature, then you probably don't). * JM can assign default priorities to tasks as they start. * JM can log task activity to a disk file for later use. Last but not least, JM has very little impact on the system itself; no low priority "CPU muncher" tasks are started, unlike some CPU usage monitor programs. JM is NOT, nor is it intended to be, nor will it ever become, a general purpose system monitor ala Xoper. JM has a number of somewhat complex features; you will need to read this documentation to fully understand it. This is especially true for the more complex task management features. JM Job Management Page 3 Users's Guide Installing JM Follow these steps to install JM: 1. Copy the "JM-Handler" file to the "L:" directory. If you have a 68000 or a 68020, copy "JM-Handler.68000" to "L:JM-Handler" instead. If you use the wrong version on those machines, your computer will certainly crash. 2. Copy the ".jmrc" file to the "S:" directory. 3. Copy the following executable files to a location in your AmigaDos search path. They should all have the "pure" bit set also, and can be made resident. JM uptime stat ps pri taskinfo If you have a 68000 or 68020, copy the ".68000" versions to those names instead. 4. Insert "JM -init" as early as possible in your s:startup-sequence file (but after "setpatch"). 5. Reboot the machine (or execute "JM -init" manually if do not wish to reboot). JM has several clients (JM, uptime, ps, etc), and a server ("JM-Handler"). "JM -init" starts the server, and "JM -halt" stops it. There is usually no reason to stop it, but it can be stopped if need be. JM will complain if it cannot find the server, or if the server version does not match the client version. If the server is already halted, and "JM -halt" is executed, JM will wait several seconds for the server to respond before giving up. JM should include these files. If it does not, then your system is incomplete or corrupt: JM.doc - This documentation file JMRexx.doc - Documentation on JM ARexx port .jmrc - The JM init file, to reside in S: JM - The JM command, 68030/40 version JM-Handler - The JM handler, 68030/40 version stat - A system status command, 68030/40 uptime - Reports system uptime, 68030/40 ps - Process status, 68030/40 pri - Change task priorities, 68030/40 taskinfo - Detailed task info, 68030/40 JM Job Management Page 4 Users's Guide JM.68000 - 68000/20 version of JM JM-Handler.68000 - 68000/20 version of JM-Handler stat.68000 - 68000/20 version of stat uptime.68000 - 68000/20 version of uptime ps.68000 - 68000/20 version of ps pri.68000 - 68000/20 version of pri taskinfo.68000 - 68000/20 version of taskinfo Once again, double check that you are running AmigaDos 2.04. JM does not handle 1.3 gracefully. JM Job Management Page 5 Users's Guide Copyright and Distribution Conditions JM is copyrighted freeware. It may be freely distributed, given the following conditions: * JM may not be sold for more than the price of a current Fish disk. Fred Fish is explicitly granted permission to distributed JM. * Written permission from the author must be obtained if JM is to be included in any commercial software package. * Written permission must also be obtained to include JM on any disk based commercial magazine. * The entire JM system must be distributed whole; pieces may not be left out, nor may they be changed. In par- ticular, you may not claim authorship of JM. * JM may be uploaded to BBS systems and electronic net- works, IF and ONLY IF those systems make no copyright or ownership claims to uploaded software. This MAY prohibit uploading to Genie, Compuserve, or other networks; please check before doing so. The copyright on JM is owned solely by the author. * Since JM is provided free of charge, no claims are made about its suitability for any particular purpose, nor the quality or robustness of the software or documentation. The author will probably make an effort to resolve bugs in the software; he simply reserves the right not to. The basic concept is that you should use it in good faith and not make a profit from it nor claim it as your own. I have had people both claim authorship of and make a profit from other free software which I have written. This is very dis- heartening to see. Please don't. Motivation for JM Why did I write JM? Some of its task management functions are not currently available elsewhere on the Amiga. (For example, the CPU ratio management is, at least for now, something that only JM does). The other reporting functions were just added to provide a complete set of utilities in one package. Some other programs provide CPU % numbers, but they usually either guess at this number based on task switch counts, or start a low priority background task which uses all unallocated CPU cycles (a kludgy solution). JM Job Management Page 6 Users's Guide JM Passive Reporting Modes General System Status JM can monitor and report information about the current Amiga multitasking environment. To obtain general system information, use the "stat" command. The general system status report looks like this: System Boot Time : 26-Jan-92 20:14:24 Uptime : (0 days) 02:26:25.840 Total idle CPU time : (0 days) 01:28:35.600 Total used CPU time : (0 days) 00:57:39.380 CPU/FPU : 68040/68040 Tasks started/finished : 113/100 Recent idle CPU % : 91.73% JM task manager is : on (0 managed tasks) JM task logging is : off (0 log failures) JM task startup watch is : on Each field will be explained in greater detail: System Boot Time: This is the date and time the JM server was started. Since "JM -init" is run early in the startup-sequence, this is also the system boot time (within a few seconds). Uptime: This is the time the system has been up. The format is: (d days) hh:mm:ss.ttt, where "ttt" are thou- sandths of a second. Total idle CPU time: This is a count of the total idle CPU time system the system was booted. All cycles which don't go to any other process are reflected here. Total used CPU time: This is the opposite of the above - a count of the CPU time used for running processes. Tasks started/finished: This is a count of the number of tasks which have been started since "JM -init" was invoked. The second number is a count of the tasks which have exited. Recent idle CPU %: This is a sliding scale of the percent of CPU time not used. In other words, if 0% of the CPU has been used, and suddenly 50% is used, this number will asymptotically approach 50%, getting there in about a minute, depending on various configuration options. JM task manager is: This value is either "on" or "off", an indicates whether JM is permitted to share the CPU un- equally among CPU bound tasks. See Job Management for details. JM Job Management Page 7 Users's Guide JM task logging is: Again, either "on" or "off". JM can log task activity to a disk file for later use. JM task startup watch is: "on" or "off". JM can watch tasks starting up, and change their priority to a given default based on the task name. If "off", this will not happen. The configurable parameters can be changed through vari- ous options to the JM command. Process Status JM provides an enhanced process status command, similar to the AmigaDos "status". Use the "ps" command to list tasks and processes. The default "ps" output lists every task in the system. The following information is printed for each task: Num - A task ID number. Since AmigaDos only assigns ID numbers to CLI processes, this is an equiva- lent for other tasks and serves as a way to specify these tasks. This number will be the same over the life of a task, given that the JM server is not stopped. This ID number can be used in the "pri" and "taskinfo" commands. Task Name - The task name, for tasks, and the process name, for processes. If the entry is a CLI process, the name will be prefixed by [CLI n], where "n" is the CLI number. Imbedded newlines are re- moved from process names. Pri - The task priority: ranges from -128 to 127. RUN Time - The "wall clock" time since this process was started. The format is: hhhh:mm:ss. CPU Time - A measure of the amount of CPU time this pro- cess has taken since it was invoked. The for- mat is hhhh:mm:ss.ttt (where ttt are thou- sandths of a second). This count is accurate to approximately 0.016 seconds on a NTSC Amiga, and 0.020 seconds on a PAL Amiga. CPU bursts less than 0.016 seconds may not be noticed by JM. The ones that are will be counted as 0.016 seconds, so this tends to average out to about the right thing in the end. JM Job Management Page 8 Users's Guide CPU % - This is a weighted percentage of the recent CPU use of this task. 100.0% would indicate that this task has take all the recent CPU time, and 0.0% means that it has take none. This is a floating percentage: if a task was taking 0.0% of the CPU, and starts to take 50%, its CPU % will ramp up from 0% to 50% over approximately one minute of real time. This can be con- trolled though various parameters to JM. Stack - The stack space in bytes allocated to this task. Use - The stack space actually in use by this task. Sometimes this will show up as "0" if JM is un- able to figure it out. There are also several options available to restrict the "ps" output to a certain set of tasks: -cli - Lists only command line interface tasks (the ones which usually show up using the AmigaDos "status" command). -m - Lists only tasks managed by JM. More detail will be given on this later. -z - Lists only tasks which have "0.0" as their current CPU use percentage. -n - Lists only tasks which do not have "0.0" as their current CPU use percentage. -bg - Lists only "background" tasks, with a priority less than 0. Same as -plt 0. -fg - Lists only "foreground" tasks, with a priority greater than or equal to 0 and less than or equal to 5. Same as -pgt -1 -plt 6. -rt - Lists only "real time" tasks, with a priority greater than 5. Same as -pgt 5. -pgt num - Lists only tasks with a priority greater than <num>. Can be combined with -plt. -plt num - Lists only tasks with a priority less than <num>. Can be combined with -pgt. -peq num - Lists only tasks with a priority equal to <num>. -ple num - Priorities less than or equal to num. JM Job Management Page 9 Users's Guide -pge num - Priorities greater than or equal to num. Misc. options: -h - Prints an extended PS header, listing the CPU and FPU type, idle CPU time, used CPU time, idle CPU %, and a few other things. -nocli - Leave out CLI numbers in task names. And options to sort the task list various ways: -name - Sort task list by name. -cpup - Sort task list by CPU %. -cput - Sort task list by CPU time. -pri - Sort task list by priority. -inv - Inverse (backwards) sort. Most of the "pruning" options to "ps" are mutually exclusive, as are the sorting options. Some options can be combined. For example, to list only CLI tasks with priorities greater than 2, in order by CPU time: ps -cli -pgt 2 -cput Uptime The "uptime" command is similar to the Unix version, except that it does not print the number of users logged in, as this is meaningless on the Amiga. "Uptime" will report the following information: up 0 days, 02:58:51, load average: 0.25, 0.23, 0.22 The first time printed is the amount of time since the Amiga was booted. There are also three numbers after the "load average". They are the average system load for the past 30 seconds, the past 2.5 minutes, and the past 5 minutes. This number is a measure of the average number of tasks waiting to run over any given time. A count of "0.00" means the CPU is unloaded. A count of "1.00" means that, on average, the CPU always had a job to run. (This would be the case, for example, if a numbercrunching pro- gram such as a ray tracer was running). A count of "2.00" means that, on average, there were always 2 tasks ready to run. This would be the case if a ray tracer and "lharc" were both running at once - each would want 100% of the CPU, hence, the load average would be 2.00. (Actually, it would be a little higher if you were typing or doing other JM Job Management Page 10 Users's Guide interactive things on the system at the same time). Detailed Task Information The "taskinfo" command can be used to list detailed infor- mation about a given task. The task can by indicated by name or ID number (the ID number is the one reported by the "ps" command): taskinfo mg taskinfo 12 Multiple task names or numbers can be given, and "taskinfo" will output information on each, separated by a newline. In addition to the fields listed by the "ps" command, "taskinfo" reports the following: Max Stack - A rough estimate of the maximum stack space used by this task since it has started. Don't place too much faith in this, since it is pos- sible for JM to miss a sudden and brief in- crease in stack space. Starttime - Date and time when the task was started. Launches - The number of times AmigaDos has switched to this task since the task was started. JM Job Management Page 11 Users's Guide JM Active Management Modes Changing Running Task Priorities JM can change the priority of running tasks, given a task name or ID number. For example: pri mg 2 # change priority of "mg" to 2 pri 79 -3 # change priority of task 79 to -3 More than one set of parameters can be given: pri task1 3 task2 4 An error is reported if the given task name or ID number does not exist, or if the priority value is out of range. Invoking Task Watch JM can watch tasks as they start up. If it sees one which it recognizes, it can immediately change the priority of this task to a given default value. This is often useful for programs which provide no built in method to save a de- fault priority. For example, suppose you run the Imagine ray tracer, and after you start it, you always manually change the priority of it to "-5" so that the rest of the system performs well during rendering. Also, suppose you use the "less" pager, and always want it to run with a pri- ority of "2" for good interactive performance during loaded system conditions. Both of these things are easy to accom- plish by using JM's watch feature. The standard way to list task names and their default pri- orities is in the "s:.jmrc" default file. However, new values may be added to a running JM server as follows: JM -watch -add MyTask1 MyPri1 MyTask2 MyPri2 ... Any number of task name and priority pairs may be given. Here is an example with real names: JM -watch -add less 2 Names added in this way will only be in effect as long as the current JM server is active. To make them permanent, put them in the s:.jmrc file. The current watch list can be listed: JM -watch -list This will produce a listing similar to the following: JM Job Management Page 12 Users's Guide Task Startup Watch List: mg 2 MEmacs 2 calendar 5 calculator 1 Note that these are not running tasks. They are simply names which JM will watch for. If it sees one start up, it will give it the indicated priority. The names are not case sensitive, nor do they include pathnames. Names can be removed from the watch list of a running JM server: JM -watch -del MyTask1 MyTask2... Also, the watch mechanism can be turned off: JM -watch -off and back on: JM -watch -on When off, tasks are started with the priority they would have had if JM was not running. The default is "on". Version 1.0 of JM can store up to 64 watch entries. Task Logging JM can keep an audit log of task activity for later use. Each time a task ends, a line is written to a disk file containing the task name, the priority, the start time of the task, the end time of the task, and total amount of CPU time taken by this task over its lifetime. If for some reason JM is unable to open or write to the log file, it will keep a count of "logging errors" and print this infor- mation in the "stat" command. The name of the log file defaults to "ram:JM.log", but can be changed in the s:.jmrc defaults file. Logging can be turned on: JM -log -on and back off again: JM -log -off JM Job Management Page 13 Users's Guide CPU Bound Task Management With faster 68030 and 68040 Amigas becoming more common each day, and with the advent of powerful CPU intensive software such as Imagine, Scenery Animator, etc., more and more Amigas are finding their way into number crunching applications. They cannot come close to the performance of high speed workstations, but they also are affordable by mere mortals, and have a large software base. The Amiga OS is brutally efficient at multitasking. A num- ber of number-crunching tasks may be running in the back- ground, and if they have low priority, there is almost no noticeable affect on foreground interactive tasks. AmigaDos is one of the best operating systems in this re- gard, outperforming even most varieties of Unix, and being far better than Apple System 7 and Windows 3.x software. However, there are limits to the Amigas flexibility in this area. Specifically, if two number-crunching tasks are vying for continuous use of the CPU, one of two cases must be true. Either 1) they both have the same priority, and share the available CPU time in a 50/50 ratio, or 2) one has a lower priority, and gets no CPU time at all, since it all goes to the higher priority task. Advanced Amiga users who run several of these types of jobs at once may wish to have more control over how their CPU cycles are allocated. JM was invented primarily to fill this need; the other reporting aspects are merely an afterthought. JM can allocate the CPU to low priority number-crunching tasks in any user defined ratio. Let us assume that we are dealing with 3 tasks. One is Scenery Animator (the terrain rendering program from Natural Graphics), one is MandelPAUG (a freeware Mandelbrot animation program), and one is "longpi" (a small freeware program which computes pi to any number of places). Normally, these tasks all want as much of the CPU as they can get. If they are all to run at once, there would be no choice but to give equal CPU time to each. JM keeps a list of tasks which we wish to "manage" by allo- cating CPU resources unequally between them. When one starts up, it is put on the management list, and is there- after allocated only its fair share of the CPU. Lets take an example, for clarity. The "JM -manage -list" command will list the tasks which JM will manage, if and when they start up. It will also list the tasks currently being managed. Here is a sample output: JM Job Management Page 14 Users's Guide Manage Watch List: SceneryAnimator 12 MandelPAUG 8 longpi 1 Managed Task List: <none> In this example, JM will watch for tasks with those three names to start up. The task name is, again, not case sen- sitive, nor does it include path names. The number after the task name is the number of CPU time quantum to allocate to this task. (The length of one time quantum can be changed; see the section on configuration of JM for de- tails). If MandelPAUG and longpi were run at once, out of each 9 time quantum, 8 would go to MandelPAUG and 1 to longpi. If SceneryAnimator was then started, out of each 21 cycles, it would get 12, MandelPAUG would get 8, and longpi would get one. In other words, the exact ratio depends on the set of running managed jobs. The more there are, the smaller the ratio of CPU time the other jobs get. Now let us assume that we have actually start up all three of those tasks. (Remember, the top list is simply the list of things JM will watch for). "JM -manage -list" now looks like this: Manage Watch List: SceneryAnimator 12 MandelPAUG 8 longpi 1 Managed Task List: [CLI 7] longpi 1/21 (4%) [CLI 9] MandelPAUG 8/21 (38%) SceneryAnimator 12/21 (57%) (Scenery Animator does not have a [CLI n] in front because I started it from workbench). Under the "Managed Task List", we see that all three programs are running. There are 21 available quantum per cycle, and longpi is getting 1 (or 4% of the CPU), MandelPAUG is getting 8 (or 38% of the CPU), and SceneryAnimator is getting 12 (or 57% of the CPU). Actually, these CPU percentages are simply computed based on the number of quantum and the manage list numbers. They are theoretical. To list the _actual_ CPU use of all managed jobs, we can use the "ps" command. Of course, "ps" normally lists 20 to 40 running tasks, and we want to see only the managed ones, so use "ps -m". Here is a partial "ps" listing from my system right now. (Partial, since I can't fit all 78 columns within the margin of this docu- ment): JM Job Management Page 15 Users's Guide Num Task_Name RUN Time CPU Time CPU% 1 [CLI 9] MandelPAUG 0:19:10 0:07:05.566 35.2% 2 SceneryAnimator 0:16:09 0:06:14.783 53.1% 3 [CLI 7] longpi 0:19:29 0:02:57.433 3.7% (I deleted 3 of "ps"s output columns). Here we can see that the actual CPU ratios are not quite as predicted. Why? Well, there are two reasons. First of all, they are ALL less than predicted because 100% of all the CPU cycles are NOT available to these three tasks, since I am typing this document into a word processor right now in the foreground. (Together they are getting a bit over 92% of the CPU). Also, we see an anomaly in that SceneryAnimator is getting less than the ratio we thought it would, even taking the above into account. This is because it is gen- erating an animation to hard disk, and while it is writing each frame, it is not using the CPU, nor does it want to. It is giving up a few percent of the cycles it could be getting. The predicted CPU percentages will only be close if all tasks want the CPU at all times. If they give it up voluntarily sometimes, they will use less than their allotment. We can also see that "MandelPAUG" has used 4:27 of CPU time compared to SceneryAnimator's 2:01. This is because I started it three minutes ahead of SceneryAnima- tor, so it has had more time to accumulate CPU time. The allocation strategy is as follows. If the "primary" running managed task wants the CPU, it gets it. If not, the cycles it does not want are split evenly among all other managed jobs. This turns out to be a good strategy in most cases. Starting Managed Jobs Which Require Interaction Lets say that 3 managed jobs are running now, and we wish to add a fourth, but the fourth requires a bit of user in- teraction before it begins numbercrunching. (Two of the three programs above are in this category). If we just start it normally, it will only get x% of the CPU, where x may be fairly small. This will make it very hard to deal with interactively. What do we do about this? Well, we can instruct JM to turn off management for a while. We do this via: JM -manage -off When JM turns off task management, all the managed tasks DO continue to run. They just do so all at the same priority, which is very low. We can then start our fourth job in peace, and interact with it as a foreground application. As soon as it is set up and number-crunching away, we can turn task management back on via: JM Job Management Page 16 Users's Guide JM -manage -on Now, this task is put into the managed queue with the other managed tasks and gets its expected ratio of CPU cycles. Tasks may be added to or deleted from the JM task manage- ment watch list in the same manner as listed for the "JM - watch" option. Namely: JM -manage -add task1 quantum1 task2 quantum2 ... JM -manage -del task1 task2 ... Note that these only affect the list of watched task names, NOT the actual running tasks. If a task is "added", but it alreay exists, its weight is modified accordingly. Changing the Weight of Running Managed Tasks The CPU weight of a running managed task may be changed via: JM -manage -mod taskname newquant If a currently running managed task named "taskname" is running, its quantum value is changed to "newquant". For example, if the old "jm -manage -list" output was: Manage Watch List: SceneryAnimator 12 MandelPAUG 8 longpi 1 Managed Task List: [CLI 7] longpi 1/9 (11%) [CLI 9] MandelPAUG 8/9 (88%) And we executed: JM -manage -mod longpi 4 The new result would be: Manage Watch List: SceneryAnimator 12 MandelPAUG 8 longpi 1 Managed Task List: [CLI 7] longpi 4/12 (33%) [CLI 9] MandelPAUG 8/12 (66%) Note that this does not affect the watch list, only the list of managed tasks actually running. JM Job Management Page 17 Users's Guide JM Customization and Configuration The .jmrc Config File How do you customize and configure JM to suite your needs? You copy the .jmrc file to your s: directory, and edit it to suite your tastes. This file has comments which attempt to explain its format and content. This comments should be left in place for future use; they are read fast, so they incur very little startup penalty. Here is a brief description of the types of things which can be put in this file. LOGSWITCH off This can be either "off" or "on". If "on", JM will log task activity to a disk file by default. LOGFILE "ram:JM.log" This is the name of the file to log task activity to, if logging is turned on. PS_CPU_TIME 5 The CPU percentage fields in the "ps" output are only up- dated once in this many seconds. 5 is a good value. The larger the value, the longer the convergence time of this percentage. (Remember, it is a sliding average, and re- flects recent historical CPU use as well as current CPU use). MANAGESWITCH on Can be "on" or "off". If "on", JM will watch for tasks to manage. If "off", it won't. WATCHSWITCH on Can be "on" or "off". If "on", JM will assign default pri- orities to newly started tasks. QUANTUM 5 The length of one management quantum in 1/10s of a second. For example, if a managed task has a value of "10", it will get 10 quantum in a row before giving up the CPU. In this case, each quantum would be 1/2 second (5/10), so the task would get the CPU for 5 seconds in a row. If the quantum time is reduced, smoother results are obtained. There is a very slight overhead penalty for this, but it should be nearly, if not actually, immeasurable on a 68030 or 68040 system. 68030/40s have no trouble with a QUANTUM of 1. JM Job Management Page 18 Users's Guide MIN_MANAGE_PRI -26 MAX_MANAGE_PRI -25 This two lines control the minimum and maximum priorities used by the managed tasks. The "current" managed task has the maximum priority, and all others have the minimum. Ob- viously, the max must be larger than the min. Each should be small, so that these managed number-crunching tasks do not affect the interactive performance of the system. TASKPRI "MEmacs" 2 Up to 64 of these lines may be present. They control the default task priority for newly started tasks, if the task watch feature is turned on. MANAGE "SceneryAnimator" 12 Up to 16 of these lines may be present. They control the number of contiguous management quantum which can be allo- cated to this task, if managed. INSTALL_DELAY 5 Some methods of starting background commands (the AmigaDos RUN command, for example) do not install the process name immediately upon invocation. Instead, the process name is "run" or some other non-descript string temporarily. This will confuse JM, which normally looks for the name immedi- ately upon startup. This parameter will tell JM to delay checking the task name for N 10ths of a second after the task first appears. This should be made as small as possible. A value of 5 to 10 should be fine for most ac- celerated hard disk systems. You may need to tweak this value for slower machines. Permitted values are 0 to 50. Use high values only as a last resort. AREXX_PORT on The JM server normally starts an ARexx port for communica- tion with other tasks. If this is not desired, this switch can be set to "off". If the value of this switch is changed and the .jmrc file is re-read, but the server is not restarted, JM will stop accepting ARexx messages, but the server port not be removed. For that reason, it is recommended that the JM server be restarted when this value is changed in the .jmrc file. JM Job Management Page 19 Users's Guide Other Options JM can be made to re-read the .jmrc file without exiting and restarting the server. Simply use: JM -rc JM currently prints no errors or warnings if the .jmrc file contents are found to be invalid. The file is simply ig- nored quietly. Also, the time quantum can be changed without having to re- read the .jmrc file via: JM -quantum <num> Where num is the new quantum length, in units of 1/10 sec. If the argument is omitted, the old value is printed. JM Job Management Page 20 Users's Guide Technical Information and Theory This section is included for people who are interested in how JM works internally. A running task has three basic types of time: 1. Idle time: (i.e., it is not using the CPU and doesn't want to). This would be the case if a task is waiting for some user input. 2. CPU bursts: This is the time a process is using the CPU as much as it can. A mostly interactive program, such as a text editor, will tend to have short CPU bursts in the range of a few 10ths of a second. A ray tracer will have long CPU bursts. 3. I/O bursts: This is the time a process spends doing I/O. This may or may not also be CPU intensive, depending on the disk controller. Amiga 3000s, for example, are very good about using only a little CPU time during HD I/O. To measure process CPU time, JM patches into the tc_Switch and tc_Launch members of the exec Task structure. These are pointers to functions which are called when tasks loose and obtain the CPU. JM points these to its own functions which remember the beginning and ending times of each CPU burst of each task. JM keeps this information around in a structure it maintains explicitly for this purpose. This structure also contains the task start time. JM uses the AmigaDos SetFunction() call to put its own code ahead of the system AddTask() and RemTask() functions. This way, it can store datestamps and other information during an AddTask(), and free the information later during a RemTask(). It also uses this mechanism to watch for tasks to which it assigns a default priority. Upon invocation with "JM -init", a "JM-Handler" is loaded from the L: directory. This handler contains code which must al- ways be present in memory, such as the new AddTask() and RemTask() code, and the code which is patched into tc_Switch and tc_Launch. There is also a process in here which listens for messages from elsewhere, and controls the "task manage- ment" parts of JM (which allocate CPU resources to tasks un- equally). JM Job Management Page 21 Users's Guide Bugs, Caveats, Disclaimers There are a few types of commonly encountered problems with JM. Here are some: * JM decides how to manage tasks and allocate priorities based on the task or process name. JM 1.1 is smarter about obtaining these names than was JM 1.0. Some invocation methods, such as the AmigaDos "run" command, do not install the process name when the task is invoked. Instead, it is installed a short time later. JM tries to compensate for this by checking process names twice: once when they start, and once a short time later. If you are running on a slow system, you may have to adjust the value of the INSTALL_DELAY parameter in the .jmrc file. * If CPU cycles are not allocated to managed tasks in the ratios you expect, it could be because one of the tasks is giving up the CPU voluntarily (to wait for a system resource, for example, or perform disk I/IO). In any case, there is a small amount of "slop" in JM's alloca- tion strategy. The percentages are approximate, accu- rate to about 1% under optimal conditions. Also remem- ber that the CPU percentages in the "ps" output are sliding averages, so the currently running managed job will tend to have a slightly higher percentage show up while it is running. * JM tries to operate in a system friendly fashion. How- ever, it is examining a few deep, dark corners of the Amiga operating system which are not meant to be exam- ined by mere mortals. I make no guarantees that JM will do anything at all in future AmigaDos releases. There is a great chance it will still work; I'm just not guaranteeing it. If it does break, I will attempt to fix it and release a new version. * Users of custom shells should be careful that any built- in "ps" command does not override the definition of the JM "ps" command. Users of SKsh and CShell will have this happen. SKsh users can remove the built-in SKsh "ps" function through "unset -b ps". Alternatively, they can alias "ps" to the JM "ps" binary. CShell users can also take this route. * If JM crashes upon invocation, check that you are using the correct version for your machine. I supply one ver- sion for 68000s and 68020s, and a separate one for 68030s and 68040s. The 68030/40 users can use both, but the second is optimized for faster CPUs. 68000/20 us- ers will likely crash their machines by attempting to run the other version. Also, make sure you are use AmigaDos 2.04. JM Job Management Page 22 Users's Guide * If you exit JM, and it crashes when restarted, it is likely because you are are running "JM -init" before "setpatch" instead of after. * If JM exits immediately with no output when you try to start the server with "JM -init", then you might be run- ning under AmigaDos 1.3. JM will not work under 1.3, nor do I have any desire to make it do so. AmigaDos 2.04 is well worth the $99 for the upgrade. * If JM complains about not being able to invoke the server, make sure that JM-Handler is in the L: directory. * If JM does not seem to "see" your entries in the .jmrc configuration file, make sure this file resides in S:, and that it is in the correct format, and that you have invoked "JM -rc" to re-read the file after any changes. * If a single tasks accumulates more than about 1.13 years of CPU time, it will "wrap" around to 0. This won't hurt anything - it is just a display anomaly. * Some screen blankers and other such things run with a priority greater than that used by JM for its managed tasks. Thus, they will leave no free cycles for the background tasks. If this is so, simply adjust the pri- orities in the s:.jmrc file, or use a different screen blanker. * Sometimes CPU time is not charged to the task you think it will be. Here are two examples. A shell may take less CPU time than you think, because some of its time is charged to the CON handler for scrolling text in the window. A screen blanker which continuously draws onto its custom screen might actually be starting up a sepa- rate task to do the drawing, and killing it once it is done, so the main screen blanker task will use very little CPU time. * Due to the manner in which AmigaDos executes programs from the command line interface, JM will not notice tasks unless they are put into the background with the AmigaDos RUN command or a similar utility. By executing a program in the foreground, (such as typing "dir"), there is no new task created. Whether this is desirable or not can be debated, but it does mean that JM will not see these tasks or be able to manage them. JM Job Management Page 23 Users's Guide * Since the CPU % printed after each task in the "ps" com- mand output is a weighted average based on recent his- torical CPU use by that task, the percentage values may not add up to exactly what you expect them to at any given time. * There is currently no graceful way to handle multiple tasks with the same name, other than always specifying them by ID number. * If JM tries to permit tasks to install their own values into the tc_UserData field of the task structure. How- ever, if the task modifies its tc_UserData field from another task or interrupt handler, this may conflict with JM. If this happens, lines of the following type may be inserted in the .jmrc file: IGNORE "taskname" This is not recommended except where strictly necessary, since the total CPU use accounting will no longer be ac- curate if these tasks take a significant amount of CPU time. JM Job Management Page 24 Users's Guide Future Enhancements By all means, feel free to send suggestions for JM to me at the address listed below. I would like to add at least the following to JM: * A graphical, resizable, xload like CPU load meter. * The use of 2.04 file change notification to eliminate the need for the "JM -rc" option to re-read the config file. * Extending the ARexx interface of JM. You can contact me via US mail: Steve Koren 405 Pulsar St. Ft. Collins, CO 80525 USA or phone: 303-226-4985 or email: koren@hpfcly.fc.hp.com koren@hpmoria.fc.hp.com JM Job Management Page 25 Users's Guide Credits and Acknowledgments JM was written using SAS C 5.10b. JM was written on an Amiga 2000 with a PP&S 68040 card. Information on register usage of routines was found in the "Amiga Programmer's Handbook", published by Sybex. Message passing examples from "Programmer's Guide to the Amiga", by Rob Peck were very useful. The output format of the "uptime" command output was styled after the Unix command of the same name. JM was written using AmigaDos 2.04. 2.04 is a great improve- ment over 1.3. Thanks to Ray Zarling for testing JM and providing useful sug- gestions and feedback. Thanks to Chris Wichura for the idea on how to be more friendly when using tc_UserData. The .jmrc file format was heavily based on the file format in- vented by Loren J. Rittle for the NewPop utility. JM Job Management Page 26 Users's Guide