Index: /trunk/doc/manual/en_US/SDKRef.xml
===================================================================
--- /trunk/doc/manual/en_US/SDKRef.xml	(revision 56624)
+++ /trunk/doc/manual/en_US/SDKRef.xml	(revision 56625)
@@ -3840,4 +3840,26 @@
       SDK. It contains exception handling and error printing code, which
       is important for reliable larger scale projects.</para>
+
+      <para>It is good practice in long-running API clients to process the
+      system events every now and then in the main thread (does not work
+      in other threads). As a rule of thumb it makes sense to process them
+      every few 100msec to every few seconds). This is done by
+      calling<programlisting>
+        mgr.waitForEvents(0);
+        </programlisting>
+      This avoids that a large number of system events accumulate, which can
+      need a significant amount of memory, and as they also play a role in
+      object cleanup it helps freeing additional memory in a timely manner
+      which is used by the API implementation itself. Java's garbage collection
+      approach already needs more memory due to the delayed freeing of memory
+      used by no longer accessible objects, and not processing the system
+      events exacerbates the memory usage. The
+      <computeroutput>TestVBox.java</computeroutput> example code sprinkles
+      such lines over the code to achieve the desired effect. In multi-threaded
+      applications it can be called from the main thread periodically.
+      Sometimes it's possible to use the non-zero timeout variant of the
+      method, which then waits the specified number of milliseconds for
+      events, processing them immediately as they arrive. It achieves better
+      runtime behavior than separate sleeping/processing.</para>
     </sect1>
   </chapter>
Index: /trunk/src/VBox/Main/glue/glue-java.xsl
===================================================================
--- /trunk/src/VBox/Main/glue/glue-java.xsl	(revision 56624)
+++ /trunk/src/VBox/Main/glue/glue-java.xsl	(revision 56625)
@@ -3892,5 +3892,4 @@
     public void waitForEvents(long tmo)
     {
-        // what to do here?
         try
         {
@@ -4695,4 +4694,11 @@
     public void waitForEvents(long tmo)
     {
+        try
+        {
+          Thread.sleep(tmo);
+        }
+        catch (InterruptedException ie)
+        {
+        }
     }
 
Index: /trunk/src/VBox/Main/glue/tests/TestVBox.java
===================================================================
--- /trunk/src/VBox/Main/glue/tests/TestVBox.java	(revision 56624)
+++ /trunk/src/VBox/Main/glue/tests/TestVBox.java	(revision 56625)
@@ -73,4 +73,5 @@
                     es.eventProcessed(listener, ev);
                 }
+                mgr.waitForEvents(0);
             }
         } catch (Exception e) {
@@ -115,4 +116,5 @@
             }
         }
+        mgr.waitForEvents(0);
     }
 
@@ -140,4 +142,5 @@
         progressBar(mgr, p, 10000);
         session.unlockMachine();
+        mgr.waitForEvents(0);
     }
 
@@ -163,4 +166,6 @@
             session1.unlockMachine();
             session2.unlockMachine();
+            mgr1.waitForEvents(0);
+            mgr2.waitForEvents(0);
         } finally {
             mgr1.cleanup();
@@ -183,4 +188,5 @@
             off += buf.length;
         }
+        mgr.waitForEvents(0);
     }
 
@@ -265,4 +271,5 @@
         }
 
+        mgr.waitForEvents(0);
         if (ws)
         {