[glibmm] Deprecated thread_init(), Thread::joinable(), *_priotity(), etc.

[Murray Cumming <murrayc src gnome org>]

commit 9f2876360109b88cbf919aab1e02eab161f1d268
Author: Murray Cumming <murrayc murrayc com>
Date:   Fri Oct 21 10:01:05 2011 +0200

    Deprecated thread_init(), Thread::joinable(), *_priotity(), etc.
    
    	* glib/src/thread.[hg|ccg]: Deprecate thread_init(), thread_supported,
    	Thread::joinable(), Thread::set_priority(), Thread::get_priority() and
    	ThreadPriority.

 ChangeLog           |    8 ++++
 glib/src/thread.ccg |   36 ++++++++++++++---
 glib/src/thread.hg  |  109 ++++++++++++++------------------------------------
 3 files changed, 69 insertions(+), 84 deletions(-)
---
diff --git a/ChangeLog b/ChangeLog
index 1a32297..a1bd3b3 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,11 @@
+2011-10-21  Murray Cumming  <murrayc murrayc com>
+
+	Deprecated thread_init(), Thread::joinable(), *_priotity(), etc.
+
+	* glib/src/thread.[hg|ccg]: Deprecate thread_init(), thread_supported,
+	Thread::joinable(), Thread::set_priority(), Thread::get_priority() and 
+	ThreadPriority.
+	
 2011-10-16  Josà Alburquerque  <jaalburqu svn gnome org>
 
 	gmmproc: Remove M4 warnings due to commas in return types.
diff --git a/glib/src/thread.ccg b/glib/src/thread.ccg
index 3ece2e4..79ca2a9 100644
--- a/glib/src/thread.ccg
+++ b/glib/src/thread.ccg
@@ -59,13 +59,19 @@ static void* call_thread_entry_slot(void* data)
 namespace Glib
 {
 
-// internal
+_DEPRECATE_IFDEF_START
+
+// This was always meant as an internal method. It is no longer called,
+// and no longer needs to be called. We are keeping it just to avoid 
+// breaking ABI, though hopefully nobody is using it anyway.
+// TODO: Remove this when we can break ABI.
 void thread_init_impl()
 {
   // Make sure the exception map is initialized before creating any thread.
   Glib::Error::register_init();
 }
 
+_DEPRECATE_IFDEF_END
 
 /**** Glib::Thread *********************************************************/
 
@@ -117,14 +123,16 @@ Thread* Thread::self()
   return reinterpret_cast<Thread*>(g_thread_self());
 }
 
-bool Thread::joinable() const
+void Thread::join()
 {
-  return gobject_.joinable;
+  g_thread_join(&gobject_);
 }
 
-void Thread::join()
+_DEPRECATE_IFDEF_START
+
+bool Thread::joinable() const
 {
-  g_thread_join(&gobject_);
+  return true; //An appropriate result now that this is deprecated because all threads are now joinable.
 }
 
 void Thread::set_priority(ThreadPriority priority)
@@ -134,15 +142,31 @@ void Thread::set_priority(ThreadPriority priority)
 
 ThreadPriority Thread::get_priority() const
 {
-  return (ThreadPriority) gobject_.priority;
+  return THREAD_PRIORITY_NORMAL; //An appropriate result now that this is deprecated because the priority concept has been removed.
 }
 
+void thread_init(GThreadFunctions* vtable)
+{
+  g_thread_init(vtable);
+  Glib::thread_init_impl();
+}
+
+bool thread_supported()
+{
+  //MSVC++ needs the != 0 to avoid an int -> bool cast warning.
+  return (g_thread_supported() != 0);
+}
+
+_DEPRECATE_IFDEF_END
+
+
 // static
 void Thread::yield()
 {
   g_thread_yield();
 }
 
+
 Thread* wrap(GThread* gobject)
 {
   return reinterpret_cast<Thread*>(gobject);
diff --git a/glib/src/thread.hg b/glib/src/thread.hg
index 708eaf1..91816cb 100644
--- a/glib/src/thread.hg
+++ b/glib/src/thread.hg
@@ -59,16 +59,13 @@ enum { THREAD_PRIORITY_NORMAL = GLIBMM_MACRO_DEFINITION_THREAD_PRIORITY_NORMAL }
  */
 #define GLIBMM_STATIC_PRIVATE_INIT { G_STATIC_PRIVATE_INIT }
 
-
 namespace Glib
 {
 
-/** Specifies the priority of a thread.
- * @note It is not guaranteed, that threads with different priorities really
- * behave accordingly. On some systems (e.g. Linux) only <tt>root</tt> can
- * increase priorities. On other systems (e.g. Solaris) there doesn't seem to
- * be different scheduling for different priorities. All in all try to avoid
- * being dependent on priorities.
+
+_DEPRECATE_IFDEF_START
+
+/** @deprecated Thread priorities no longer have any effect.
  */
 _WRAP_ENUM(ThreadPriority, GThreadPriority, NO_GTYPE)
 
@@ -84,6 +81,8 @@ _WRAP_ENUM(ThreadPriority, GThreadPriority, NO_GTYPE)
 /*! @var ThreadPriority THREAD_PRIORITY_URGENT
  * The highest priority.
  */
+ 
+_DEPRECATE_IFDEF_END
 
 
 /** @defgroup Threads Threads
@@ -95,46 +94,18 @@ _WRAP_ENUM(ThreadPriority, GThreadPriority, NO_GTYPE)
 enum NotLock { NOT_LOCK };
 enum TryLock { TRY_LOCK };
 
+_DEPRECATE_IFDEF_START
+
 /** Initializes the GLib thread system.
- * Before you use a thread related function in glibmm, you should initialize
- * the thread system.  This is done by calling Glib::thread_init().
- *
- * @note You should only call thread_init() with a non-<tt>0</tt> parameter
- * if you really know what you are doing.
- *
- * @note thread_init() must not be called directly or indirectly as
- * a callback from glibmm.  Also no mutexes may be currently locked while
- * calling thread_init().
- *
- * thread_init() might only be called once.  On the second call it will
- * abort with an error.  If you want to make sure that the thread system
- * is initialized, you can do that too:
- * @code
- * if(!Glib::thread_supported()) Glib::thread_init();
- * @endcode
- * After that line either the thread system is initialized, or the program
- * will abort if no thread system is available in GLib, i.e. either
- * @c G_THREADS_ENABLED is not defined or @c G_THREADS_IMPL_NONE is defined.
- *
- * If no thread system is available and @a vtable is <tt>0</tt> or if not all
- * elements of @a vtable are non-<tt>0</tt>, then thread_init() will abort.
- *
- * @note To use thread_init() in your program, you have to link with the
- * libraries that the command <tt>pkg-config&nbsp;--libs&nbsp;gthread-2.0</tt>
- * outputs.  This is not the case for all the other thread related functions
- * of glibmm.  Those can be used without having to link with the thread
- * libraries.  (You @em have to link with <tt>gthread-2.0</tt> if you actually
- * want to use threads in your application, though.)
- *
- * @param vtable A function table of type @c GThreadFunctions, that provides
- * the entry points to the thread system to be used.
+ * @deprecated Calling thread_init() is no longer necessary and no longer has any effect.
  */
-inline void thread_init(GThreadFunctions* vtable = 0);
+void thread_init(GThreadFunctions* vtable = 0);
 
 /** Returns whether the thread system is initialized.
  * @return @c true, if the thread system is initialized.
+ * @deprecated This is no longer useful, because the thread system is always initialized.
  */
-inline bool thread_supported();
+bool thread_supported();
 
 
 class Mutex;
@@ -243,11 +214,6 @@ public:
    */
   static Thread* self();
 
-  /** Returns whether the thread is joinable.
-   * @return Whether the thread is joinable.
-   */
-  bool joinable() const;
-
   /** Waits until the thread finishes.
    * Waits until the thread finishes, i.e. the slot, as given to create(),
    * returns or g_thread_exit() is called by the thread.  (Calling
@@ -257,6 +223,14 @@ public:
    */
   void join();
 
+_DEPRECATE_IFDEF_START
+  /** Returns whether the thread is joinable.
+   * @return Whether the thread is joinable.
+   *
+   * @deprecated All threads are now joinable.
+   */
+  bool joinable() const;
+  
   /** Changes the priority of the thread to @a priority.
    * @note It is not guaranteed, that threads with different priorities really
    * behave accordingly.  On some systems (e.g. Linux) only @c root can
@@ -264,14 +238,20 @@ public:
    * to be different scheduling for different priorities.  All in all try to
    * avoid being dependent on priorities.
    * @param priority A new priority for the thread.
+   *
+   * @deprecated Thread priorities no longer have any effect.
    */
   void set_priority(ThreadPriority priority);
 
   /** Returns the priority of the thread.
    * @return The thread's priority.
+   *
+   * @deprecated Thread priorities no longer have any effect.
    */
   ThreadPriority get_priority() const;
 
+_DEPRECATE_IFDEF_END
+
   /** Gives way to other threads waiting to be scheduled.
    * This function is often used as a method to make busy wait less evil.  But
    * in most cases, you will encounter, there are better methods to do that.
@@ -314,6 +294,7 @@ Thread* wrap(GThread* gobject);
  * @code
  * Glib::StaticMutex mutex = GLIBMM_STATIC_MUTEX_INIT;
  * @endcode
+ *
  * A StaticMutex can be used without calling Glib::thread_init(), it will
  * silently do nothing then.  That will also work when using the implicit
  * conversion to Mutex&, thus you can safely use Mutex::Lock with a
@@ -335,13 +316,13 @@ struct StaticMutex
 #endif
 };
 
+_DEPRECATE_IFDEF_END
+
 /** Represents a mutex (mutual exclusion).
  * It can be used to protect data against shared access.  Try to use
  * Mutex::Lock instead of calling lock() and unlock() directly&nbsp;--
  * it will make your life much easier.
  *
- * @note Before creating a Glib::Mutex, Glib::thread_init() has to be called.
- *
  * @note Glib::Mutex is not recursive, i.e. a thread will deadlock, if it
  * already has locked the mutex while calling lock().  Use Glib::RecMutex
  * instead, if you need recursive mutexes.
@@ -625,26 +606,18 @@ public:
    * It is good practice to hold the same lock as the waiting thread, while calling 
    * this method, though not required.
    *
-   * @note This method can also be used if @a Glib::thread_init() has not yet been 
-   * called and will do nothing then.
    */
   void signal();
 
   /** If threads are waiting for this @a Cond, all of them are woken up.
    * It is good practice to hold the same lock as the waiting thread, while calling 
    * this method, though not required.
-   *
-   * @note This method can also be used if @a Glib::thread_init() has not yet been 
-   * called and will do nothing then.
    */
   void broadcast();
 
   /** Waits until this thread is woken up on this @a Cond.
    * The mutex is unlocked before falling asleep and locked again before resuming.
    *
-   * This method can also be used if @a Glib::thread_init() has not yet been 
-   * called and will immediately return then. 
-   *
    * @param mutex a @a Mutex that is currently locked.
    * 
    * @note It is important to use the @a wait() and @a timed_wait() methods
@@ -659,9 +632,6 @@ public:
   /** Waits until this thread is woken up on this @a Cond, but not longer than until the time, that is specified by @a abs_time.
    * The mutex is unlocked before falling asleep and locked again before resuming.
    *
-   * This function can also be used, if @a Glib::thread_init() has not yet been 
-   * called and will immediately return @c true then. 
-   *
    * @param mutex a @a Mutex that is currently locked.
    * @param abs_time a max time to wait.
    * 
@@ -739,26 +709,9 @@ private:
 /***************************************************************************/
 
 // internal
-void thread_init_impl();
-
-/* This function must be inline, to avoid an unnecessary dependency on
- * libgthread even if the thread system is not used.  libgthread might
- * not even be available if GLib was compiled without thread support.
+/** @deprecated This was always for internal glibmm use and is now unecessary even inside glibmm.
  */
-inline
-void thread_init(GThreadFunctions* vtable)
-{
-  g_thread_init(vtable);
-  Glib::thread_init_impl();
-}
-
-inline
-bool thread_supported()
-{
-  //MSVC++ needs the != 0 to avoid an int -> bool cast warning.
-  return (g_thread_supported() != 0);
-}
-
+void thread_init_impl();
 
 /**** Glib::Mutex::Lock ****************************************************/