* Fixed the documentation for sleep().

* Changed the implementation of sleep() on Windows such that a yield will not be forced upon the user if they pass an interval that evaluates to zero.  For more information regarding Sleep(0), see the MSDN docs.

git-svn-id: http://svn.dsource.org/projects/druntime/trunk@43 4a9d5153-6564-4b3f-b5e1-7e8e9dac548f

diff --git a/src/common/core/thread.d b/src/common/core/thread.d
index ef8984b63b9a4dcba6c72b9394e04e79ee4997a4..f0712a607328dd02521825e89a4e44c44cf09fe6 100644 (file)
--- a/src/common/core/thread.d
+++ b/src/common/core/thread.d
@@ -111,8 +111,8 @@ version( Windows )
             // NOTE: No GC allocations may occur until the stack pointers have
             //       been set and Thread.getThis returns a valid reference to
             //       this thread object (this latter condition is not strictly
-            //       necessary on Win32 but it should be followed for the sake
-            //       of consistency).
+            //       necessary on Windows but it should be followed for the
+            //       sake of consistency).
 
             // TODO: Consider putting an auto exception object here (using
             //       alloca) forOutOfMemoryError plus something to track
@@ -243,8 +243,8 @@ else version( Posix )
             // NOTE: No GC allocations may occur until the stack pointers have
             //       been set and Thread.getThis returns a valid reference to
             //       this thread object (this latter condition is not strictly
-            //       necessary on Win32 but it should be followed for the sake
-            //       of consistency).
+            //       necessary on Windows but it should be followed for the
+            //       sake of consistency).
 
             // TODO: Consider putting an auto exception object here (using
             //       alloca) forOutOfMemoryError plus something to track
@@ -479,7 +479,7 @@ class Thread
             return;
         }
 
-        version( Win32 )
+        version( Windows )
         {
             m_addr = m_addr.init;
             CloseHandle( m_hndl );
@@ -515,7 +515,7 @@ class Thread
     }
     body
     {
-        version( Win32 ) {} else
+        version( Windows ) {} else
         version( Posix )
         {
             pthread_attr_t  attr;
@@ -535,7 +535,7 @@ class Thread
         //       and causing memory to be collected that is still in use.
         synchronized( slock )
         {
-            version( Win32 )
+            version( Windows )
             {
                 m_hndl = cast(HANDLE) _beginthreadex( null, m_sz, &thread_entryPoint, cast(void*) this, 0, &m_addr );
                 if( cast(size_t) m_hndl == 0 )
@@ -573,7 +573,7 @@ class Thread
      */
     final Object join( bool rethrow = true )
     {
-        version( Win32 )
+        version( Windows )
         {
             if( WaitForSingleObject( m_hndl, INFINITE ) != WAIT_OBJECT_0 )
                 throw new ThreadException( "Unable to join thread" );
@@ -690,7 +690,7 @@ class Thread
             return false;
         }
 
-        version( Win32 )
+        version( Windows )
         {
             uint ecode = 0;
             GetExitCodeThread( m_hndl, &ecode );
@@ -737,7 +737,7 @@ class Thread
      */
     final int priority()
     {
-        version( Win32 )
+        version( Windows )
         {
             return GetThreadPriority( m_hndl );
         }
@@ -761,7 +761,7 @@ class Thread
      */
     final void priority( int val )
     {
-        version( Win32 )
+        version( Windows )
         {
             if( !SetThreadPriority( m_hndl, val ) )
                 throw new ThreadException( "Unable to set thread priority" );
@@ -805,7 +805,7 @@ class Thread
      * Example:
      * ------------------------------------------------------------------------
      *
-     * Thread.sleep( 500 );        // sleep for 50 milliseconds
+     * Thread.sleep( 500_000 );    // sleep for 50 milliseconds
      * Thread.sleep( 50_000_000 ); // sleep for 5 seconds
      *
      * ------------------------------------------------------------------------
@@ -817,7 +817,7 @@ class Thread
     }
     body
     {
-        version( Win32 )
+        version( Windows )
         {
             enum : uint
             {
@@ -825,9 +825,14 @@ class Thread
                 MAX_SLEEP_MILLIS = uint.max - 1
             }
 
-            period = period < TICKS_PER_MILLI ?
-                        1 :
-                        period / TICKS_PER_MILLI;
+            // NOTE: In instances where all other threads in the process have a
+            //       lower priority than the current thread, the current thread
+            //       will not yield with a sleep time of zero.  However, unlike
+            //       yield(), the user is not asking for a yield to occur but
+            //       only for execution to suspend for the requested interval.
+            //       Therefore, expected performance may not be met if a yield
+            //       is forced upon the user.
+            period /= TICKS_PER_MILLI;
             while( period > MAX_SLEEP_MILLIS )
             {
                 Sleep( MAX_SLEEP_MILLIS );
@@ -882,7 +887,7 @@ class Thread
      */
     static void yield()
     {
-        version( Win32 )
+        version( Windows )
         {
             // NOTE: Sleep(1) is necessary because Sleep(0) does not give
             //       lower priority threads any timeslice, so looping on
@@ -913,7 +918,7 @@ class Thread
         // NOTE: This function may not be called until thread_init has
         //       completed.  See thread_suspendAll for more information
         //       on why this might occur.
-        version( Win32 )
+        version( Windows )
         {
             return cast(Thread) TlsGetValue( sm_this );
         }
@@ -1083,7 +1088,7 @@ class Thread
      */
     static this()
     {
-        version( Win32 )
+        version( Windows )
         {
             PRIORITY_MIN = -15;
             PRIORITY_MAX =  15;
@@ -1153,7 +1158,7 @@ private:
     //
     // Standard types
     //
-    version( Win32 )
+    version( Windows )
     {
         alias uint TLSKey;
         alias uint ThreadAddr;
@@ -1177,7 +1182,7 @@ private:
     //
     // Standard thread data
     //
-    version( Win32 )
+    version( Windows )
     {
         HANDLE          m_hndl;
     }
@@ -1209,7 +1214,7 @@ private:
     //
     static void setThis( Thread t )
     {
-        version( Win32 )
+        version( Windows )
         {
             TlsSetValue( sm_this, cast(void*) t );
         }
@@ -1276,7 +1281,7 @@ private:
     Context*            m_curr;
     bool                m_lock;
 
-    version( Win32 )
+    version( Windows )
     {
         uint[8]         m_reg; // edi,esi,ebp,esp,ebx,edx,ecx,eax
     }
@@ -1437,7 +1442,7 @@ private:
     {
         assert( t );
         assert( t.next || t.prev );
-        version( Win32 )
+        version( Windows )
         {
             // NOTE: This doesn't work for Posix as m_isRunning must be set to
             //       false after the thread is removed during normal execution.
@@ -1495,7 +1500,7 @@ extern (C) void thread_init()
     //       exist to be scanned at this point, it is sufficient for these
     //       functions to detect the condition and return immediately.
 
-    version( Win32 )
+    version( Windows )
     {
         Thread.sm_this = TlsAlloc();
         assert( Thread.sm_this != TLS_OUT_OF_INDEXES );
@@ -1557,7 +1562,7 @@ extern (C) void thread_init()
  */
 extern (C) void thread_attachThis()
 {
-    version( Win32 )
+    version( Windows )
     {
         Thread          thisThread  = new Thread();
         Thread.Context* thisContext = &thisThread.m_main;
@@ -1697,7 +1702,7 @@ extern (C) void thread_suspendAll()
      */
     void suspend( Thread t )
     {
-        version( Win32 )
+        version( Windows )
         {
             if( t.m_addr != GetCurrentThreadId() && SuspendThread( t.m_hndl ) == 0xFFFFFFFF )
             {
@@ -1841,7 +1846,7 @@ body
      */
     void resume( Thread t )
     {
-        version( Win32 )
+        version( Windows )
         {
             if( t.m_addr != GetCurrentThreadId() && ResumeThread( t.m_hndl ) == 0xFFFFFFFF )
             {
@@ -1962,7 +1967,7 @@ body
                 scan( c.bstack, c.tstack + 1 );
         }
     }
-    version( Win32 )
+    version( Windows )
     {
         for( Thread t = Thread.sm_tbeg; t; t = t.next )
         {
@@ -2242,7 +2247,7 @@ private
         }
         else
         {
-            version( Win32 )
+            version( Windows )
                 version = AsmX86_Win32;
             else version( Posix )
                 version = AsmX86_Posix;
@@ -2761,7 +2766,7 @@ class Fiber
      */
     static Fiber getThis()
     {
-        version( Win32 )
+        version( Windows )
         {
             return cast(Fiber) TlsGetValue( sm_this );
         }
@@ -2779,7 +2784,7 @@ class Fiber
 
     static this()
     {
-        version( Win32 )
+        version( Windows )
         {
             sm_this = TlsAlloc();
             assert( sm_this != TLS_OUT_OF_INDEXES );
@@ -3148,7 +3153,7 @@ private:
     //
     static void setThis( Fiber f )
     {
-        version( Win32 )
+        version( Windows )
         {
             TlsSetValue( sm_this, cast(void*) f );
         }