sched: added documentation for affinity setting functions.

1 files changed, 73 insertions, 0 deletions

diff --git a/gruel/src/include/gruel/thread.h b/gruel/src/include/gruel/thread.h
index 0427a8efc..595b7b1ac 100644
--- a/gruel/src/include/gruel/thread.h
+++ b/gruel/src/include/gruel/thread.h
@@ -39,6 +39,8 @@ namespace gruel {
   typedef boost::mutex::scoped_lock        scoped_lock;
   typedef boost::condition_variable        condition_variable;
 
+  /*! \brief a system-dependent typedef for the underlying thread type.
+   */
 #if defined(_WIN32) || defined(__WIN32__) || defined(WIN32)
   typedef HANDLE gr_thread_t;
 #elif defined(macintosh) || defined(__APPLE__) || defined(__APPLE_CC__)
@@ -47,12 +49,83 @@ namespace gruel {
   typedef pthread_t gr_thread_t;
 #endif
 
+  /*! \brief Get the current thread's ID as a gr_thread_t
+   *
+   * We use this when setting the thread affinity or any other
+   * low-level thread settings. Can be called withing a GNU Radio
+   * block to get a reference to its current thread ID.
+   */
   GRUEL_API gr_thread_t get_current_thread_id();
+
+  /*! \brief Bind the current thread to a set of cores.
+   *
+   * Wrapper for system-dependent calls to set the affinity of the
+   * current thread to the processor mask. The mask is simply a
+   * 1-demensional vector containing the processor or core number from
+   * 0 to N-1 for N cores.
+   *
+   * Note: this does not work on OSX; it is a nop call since OSX does
+   * not support the concept of thread affinity (and what they do
+   * support in this way since 10.5 is not what we want or can use in
+   * this fashion).
+   */
   GRUEL_API void thread_bind_to_processor(const std::vector<unsigned int> &mask);
+
+  /*! \brief Convineince function to bind the current thread to a single core.
+   *
+   * Wrapper for system-dependent calls to set the affinity of the
+   * current thread to a given core from 0 to N-1 for N cores.
+   *
+   * Note: this does not work on OSX; it is a nop call since OSX does
+   * not support the concept of thread affinity (and what they do
+   * support in this way since 10.5 is not what we want or can use in
+   * this fashion).
+   */
   GRUEL_API void thread_bind_to_processor(unsigned int n);
+
+  /*! \brief Bind a thread to a set of cores.
+   *
+   * Wrapper for system-dependent calls to set the affinity of the
+   * given thread ID to the processor mask. The mask is simply a
+   * 1-demensional vector containing the processor or core number from
+   * 0 to N-1 for N cores.
+   *
+   * Note: this does not work on OSX; it is a nop call since OSX does
+   * not support the concept of thread affinity (and what they do
+   * support in this way since 10.5 is not what we want or can use in
+   * this fashion).
+   */
   GRUEL_API void thread_bind_to_processor(gr_thread_t thread, const std::vector<unsigned int> &mask);
+
+
+  /*! \brief Convineince function to bind the a thread to a single core.
+   *
+   * Wrapper for system-dependent calls to set the affinity of the
+   * given thread ID to a given core from 0 to N-1 for N cores.
+   *
+   * Note: this does not work on OSX; it is a nop call since OSX does
+   * not support the concept of thread affinity (and what they do
+   * support in this way since 10.5 is not what we want or can use in
+   * this fashion).
+   */
   GRUEL_API void thread_bind_to_processor(gr_thread_t thread, unsigned int n);
+
+  /*! \brief Remove any thread-processor affinity for the current thread.
+   *
+   * Note: this does not work on OSX; it is a nop call since OSX does
+   * not support the concept of thread affinity (and what they do
+   * support in this way since 10.5 is not what we want or can use in
+   * this fashion).
+   */
   GRUEL_API void thread_unbind();
+
+  /*! \brief Remove any thread-processor affinity for a given thread ID.
+   *
+   * Note: this does not work on OSX; it is a nop call since OSX does
+   * not support the concept of thread affinity (and what they do
+   * support in this way since 10.5 is not what we want or can use in
+   * this fashion).
+   */
   GRUEL_API void thread_unbind(gr_thread_t thread);
 
 } /* namespace gruel */