\/\/\ Built-ins: Mod1-RClick Focus the clicked window, but suppress raising Mod1-RClick-drag Focus the clicked window, suppress raising, resizing the window from its nearest corner until drag completes Mod1-LClick Focus and raise the clicked window Mod1-LClick-drag Focus and raise the clicked window, moving the window until the drag completes * Mod1-l Switch to virtual desktop to the right (if exists) * Mod1-h Switch to virtual desktop to the left (if exists) Mod1-j Lower focused window, if the focused window is in "allscreen" mode it will simply be fullscreened first without lowering Mod1-k [-k [-k] Raise focused window [a second k raises and [-k] [-k]] fullscreens the window [a third k raises and "allscreens" without a visible border [a fourth k raises and fullscreens across all heads [a fifth k raises and "allscreens" across all heads]]] Mod1-Shift-k Shelve focused window and switch to the shelf context Mod1-Shift-j Migrate the focused window from the shelf to the last focused virtual desktop, switch to that virtual desktop, and focus the migrated window * Mod1-Shift-l Migrate the focused window to the virtual desktop to the right (if exists), keeping the window focused * Mod1-Shift-h Migrate the focused window to the virtual desktop to the left (if exists), keeping the window focused Mod1-v Create a new virtual desktop and switch to it Mod1-Shift-v Create a new virtual desktop, move the focused window to it, and switch to it * Mod1-Space Switch to the most recently used virtual desktop (like Mod1-Tab but for virtual desktops) * Mod1-Shift-Space Switch to the most recently used virtual desktop, bringing the focused window with Mod1-` Alternate between shelf (if populated) and virtual desktop contexts Mod1-s Shelve the focused window without switching to the shelf, adopting the newly shelved window as the focused window within the shelf * Mod1-Tab Focus and raise the next window in the current context (shelf or virtual desktop), the focused window is not 'committed' as the MRU window until Mod1 is released, so you may peruse intermediate windows without affecting the order until releasing Mod1. In multihead configurations the next window selection is confined to the current screen. Mod1-Shift-Tab Identical to Mod1-Tab except switches to the MRU window on another screen in a multihead configuration Mod1-d Request the client destroy the focused window, or destroy the current virtual desktop when no windows exist on it Mod1-Shift-d XKillClient the focused window (useful for misbehaving clients) Mod1-Enter Alternate between full-screen and windowed dimensions for the focused window Mod1-[ [-[] Reconfigure the focused window to fill the left half of the screen [ left bottom quarter of screen ] Mod1-] [-]] Reconfigure the focused window to fill the right half of the screen [ right top quarter of screen ] Mod1-Shift-[ [-[] Reconfigure the focused window to fill the top half of the screen [ top left quarter of screen ] Mod1-Shift-] [-]] Reconfigure the focused window to fill the bottom half of the screen [ bottom right quarter of screen ] Mod1-Semicolon Toggle monitoring overlays (when active vwm becomes a compositing manager, which is slower) Mod1-Apostrophe Discard the "snowflakes" region of the focused window's monitoring overlay Mod1-Right Increase monitoring frequency (when overlays are active, too high a frequency can overload X) Mod1-Left Decrease monitoring frequency, the lowest setting halts monitoring) Mod1-Esc-Esc-Esc Exit vwm (if vwm is the child of your X server, X exits too, so your X clients all lose their connection and die. However, your clients are running under screen, and if your X server didn't exit, they won't lose their X connection.) *'s above indicate commands which initiate an MRU-update to be committed on the next Mod1 release. One may traverse windows and desktops without affecting their MRU order by returning to the original initiating window and/or desktop before releasing Mod1. This permits one to do quite a lot of things under a single, long-duration Mod1 press only committing to a potentially different focused window/desktop at the very end. Think of the Mod1 release as a transaction commit when coupled with the *'d commands. If a simultaneous second Mod1 is pressed at any point during a *'d command, the window (and its desktop) focused when the *'d command began will immediately be refocused - but not raised. This is intentional to simplify the arranging of obscured focused windows. If you find yourself restored to a desktop full of windows where your focused window is totally obscured/invisible, simply press Mod1-k to raise it if desired. At any point during a *'d operation one may (re)press a second Mod1 to return to the origin, it is not limited to a single use. Default launchers (configure by editing launchers.def and rebuild): Mod1-x xterm Mod1-b iceweasel Mod1-g gimp Mod1-. xlock Mod1-- xset -dpms s off Mod1-= xset +dpms s on General: Newly created windows are raised but not focused unless they are the first window on an otherwise empty virtual desktop, then they are focused as well. When new windows appear on a populated virtual desktop, they are inserted immediately after the currently focused window in the windows list, so a Mod1-Tab will immediately focus new windows. Windows are kept in a MRU (Most Recently Used) order, keeping it efficient to alternate between an evolving set of active windows. The shelf is a sort of omnipresent and limited virtual desktop always available via Mod1-`, it only shows a single window at a time, Mod1-Tab cycles through the shelved windows. I use it as a place to stow xterms running backround processes I would like to retain the ability to observe the output of or interact with occasionally. Programs like transmission-gtk, cmus, wpa_supplicant under xterm, sometimes even iceweasel sessions find themselves in my shelf on a regular basis. Multihead/Xinerama: In multihead configurations new windows are placed on the screen containing the pointer if that screen is empty. Should the pointer be on a non-empty screen, then new windows are placed on the screen containing the currently focused window. New windows will automatically be focused if the screen they were placed on is empty, even if their virtual desktop is not, which is a divergence from the single-headed behavior where only lone windows on virtual desktops are automatically focused. Composite/Monitoring: One reason vwm was created was to provide a simplified platform for the research and development of a window manager with integrated omnipresent first-class local process monitoring. Early attempts were made to modify an existing window manager (WindowMaker) which produced unsatisfactory though inspiring results. The window managers vwm[12] were created shortly after to flesh out the interaction model and solidify an perfectly usable and easily modified window manager foundation, while libvmon was created in parallel to facilitate the efficient process monitoring required for such a task. After a number of iterations it was found that the Composite extension (along with the accompanying Damage and Render extensions) would give the best results on a modern Xorg linux system. Compositing hurts the rendering performance of X applications significantly however, so a hybrid model has been employed. Monitoring overlays visibility is toggled using Mod1-Semicolon, the sample rate is increased using Mod1-Right, and decreased using Mod1-Left. When the monitoring is not visible, vwm3 continues to leave X in immediate rendering mode with no additional overhead in the rendering pipeline, just like vwm2. The only additional overhead is the cost of regularly sampling process statistics and maintaining the state of window overlays (which does involve some X rendering of graphs and text, but does not introduce overhead to the drawing of client windows). When monitoring overlays are made visible vwm3 temporarily becomes a compositing manager, redirecting the rendering of all windows to offscreen memory and assuming the responsibility of drawing all damaged contents to the root window on their behalf. This is what gives vwm3 the opportunity to draw alpha-blended contextual monitoring data over all of the windows, but it does come with a cost. Most modern GNU/Linux desktop environments are full-time composited, meaning all X clients are redirected at all times. This makes their draws more costly and latent due to all the additional copies being performed. Depending on how things have been implemented, in the interests of supporting things like transparent windows it also generally results in overlapping window regions being drawn repeatedly for every overlapping window from the bottom-up rather than just the top one. In vwm3 transparent windows are not supported, and shape windows (xeyes) are made rectangular in composited mode. This is so overlapping regions are only drawn once for the top windows having damage per burst of screen updates. Immediate rendering mode is restored upon disabling the monitoring overlays, restoring the drawing performance to vwm[12] levels where vwm3 is completely out of the drawing loop. Here are some relevant things worth noting: - The monitoring is only heirarchical if your kernel is configured with CONFIG_CHECKPOINT_RESTORE, which seems to be common nowadays. This is required for the /proc/$pid/task/$tid/children files, which is what libvmon uses to efficiently scope monitoring to just the descendants of the explicitly monitored client precesses. - tmux orphans its backend process immediately at startup, discarding its parent->child relationship, so you don't get any monitoring of the commands running in your local tmux session. Use GNU screen instead. - GNU screen orphans its backend on detach, so on reattach you've lost the parent->child relationship and find yourself in the same situation tmux puts you in immediately. I've developed an adopt() system call patch for the linux kernel to enable adopting orphans in this situation, but it hasn't been accepted. With this patch and a one line change to GNU screen the parent->child relationship is restored on reattach. You may find patches for adding the adopt() system call to Linux and its integration into GNU screen in the patches/ subdirectory. - The top row of the overlays shows: Total CPU Idle % (cyan): The height of every cyan vertical line reflects the %age of ticks since the previous sample which were spent in the idle task. Total CPU IOWait % (red): The height of every red vertical line reflects the %age of ticks since the previous sample which were lost to IO wait. Many people don't understand this correctly. This reflects opportunities to execute something other than the idle task which were lost because _all_ runnable tasks at the time were blocked in IO. An absence of IOWait does not mean nothing is blocked on IO. It just means there weren't opportunities to execute something which were lost due to waiting on IO. For example, lets say you have a dual core machine, and you launch two "yes > /dev/null &" commands. These two yes commands are essentially busy loops writing "yes" to /dev/null, they will always be runnable, and you will see a top row in the overlay devoid of any cyan _or_red_ while they execute. While they execute run something like: "sudo echo 2 > /proc/sys/vm/drop_caches && du /" Still no IOWait in the top row. We know that du is blocking on IO, the caches are empty, but because there is always something runnable on the two cores thanks to the two yes commands, we'll never see IOWait. The other runnable processes mask the IOWait from our visibility. Now kill the two yes commands and rerun the du command, watch the top row. Some red should appear, the red indicates that there was CPU time available for running something, and the _only_ things available for that time was blocked in IO. Had there something else runnable, we wouldn't see the time lost to IOWait. When you see IOWait time, it's just saying nothing executed for that time, not for lack of any runnable tasks, just that all runnable tasks were blocked. It's still of value, but easily obscured on a system with any cpu-bound tasks constantly running. - The per-task (processes or threads) rows of the overlays show: User CPU % (cyan): The height of every cyan vertical line reflects the %age of ticks since the previous sample which were spent executing this task in the user context. System CPU % (red): The height of every red vertical line reflects the %age of ticks since the previous sample which were spent executing this task in kernel/system context. Task monitoring beginning and ending is indicated with solid and checkered vertical bars, respectively. These generally coincide with the task clone and exit, but not always, especially the cloning. - You can pause sampling by lowering its rate (Mod1-Left) to 0Hz. Just be aware that this also pauses the updating of the overlay contents, so window resizes won't be adapted to in the overlay until increasing the sample rate (Mod1-Right). Pausing is useful if you've seen something interesting and would like to screenshot, study, or discuss. BTW, to take a screenshot when composited you have to capture the root window. If you capture the client window, you won't get the overlays, you'll just get the redirected window contents. Compositing mode composites everything into the root window, when you're interacting with the composited vwm3, you're looking at the root window the entire time. - The sample rate will automatically be lowered by vwm3 when it detects that it's having trouble maintaining the current one. If you have many windows or have a slow or heavily loaded processor/GPU they can become bottlenecks, especially at higher sample rates. Rather than continuing to bog down your X server (Xorg is not good at fairly scheduling clients under GPU contention), vwm3 will simply back off the sample rate as if you had hit Mod1-Left, to try ameliorate rather than exacerbate the situation. - The monitoring is implemented using sampling, not tracing. Below the current process heirarchy for every window there is an exited tasks snowflakes section filling the remaining space. Do not mistake this for something lossless like bash history or strace output, it's lossy since it's produced from sampled data. In part to try avoid interpretation of these as a reliable process history I refer to them as snowflakes in the code, since they fall downwards and sideways. With sufficiently high sample rates the output starts to take on the appearance of tracing, and while it may happen to capture every process in slower executions, most automata will execute entire commands in the time between samples. So try keep this in mind before thinking something's broken because you don't see something you expected in the snowflakes. Some artifacts you might notice due to this which are not bugs are: - "#missed it!" being shown as the command name, this happens when libvmon caught the process but the process exited before libvmon caught a sample of the name. - A parent's command name in the child when a different command was executed. In UNIX systems processes fork before execing the new command, in that window of time between the fork and exec, the child process is a clone of the parent, command and argv included. Sometimes the sample catches at just the right moment to see this in action. - Varying outputs in seeming identical actions. Things like simply launching xterm may produce no snowflakes at all in the new xterm, or a few like "bash" "dircolors -b" and "utempter add :0", especially if you have the sample rate turned up and cause some load on the system to slow the xterm and interactive bash startup scripts down. - In the interests of being efficient, nothing is being logged historically. The snowflakes area is all you get, which is limited to the free pixel space below the instantaneous process heirarchy within the window. Everything which falls off the edges of the screen is lost forever, with the exception of windows which have been made smaller than they were. You cannot scroll down or to the right to see older snowflakes or graphs. You cannot search the snowflakes. The native text and numeric representations of the sampled data is not kept any longer than the current sample, just long enough to update the overlays. From that point on the information exists only as visualized pixels in the overlay layers with no additional indexing or relationships being maintained with the currently monitored state. - You can wipe the snowflakes of the focused window with Mod1-Apostrophe - The client PID is found via the _NET_WM_PID X property. This must be set by the client, and not all clients cooperate (xpdf is one I've noticed). This is annoying especially considering the vast majority of X clients run on modern systems are local clients connected via UNIX domain sockets. These sockets support ancillary messages including SCM_CREDENTIALS, which contains the pid of the connected process. Some investigation into the Xorg sources found it already queries this information and has it on hand, but doesn't bother setting the _NET_WM_PID property even though it's well- positioned to do so. I've developed and submitted upstream a patch for Xorg which sets _NET_WM_PID on local connections, it complements vwm3 nicely. You can find the patch in the patches directory. - There are around 5 files kept open in /proc for every task monitored by vwm. This applies to children processes and threads alike, so on a busy system it's not unrealistic to exceed 1024, a common default open files ulimit for GNU/Linux distributions. You can generally change this limit for your user via configuration in /etc/security/limits.conf or /etc/security/limits.d/. TODO finish and polish this readme...