GtkSharp/doc/en/Gdk/Threads.xml

<Type Name="Threads" FullName="Gdk.Threads">
  <TypeSignature Language="C#" Value="public class Threads" Maintainer="John Luke" />
  <AssemblyInfo>
    <AssemblyName>gdk-sharp</AssemblyName>
    <AssemblyPublicKey>
    </AssemblyPublicKey>
    <AssemblyVersion>2.12.0.0</AssemblyVersion>
  </AssemblyInfo>
  <ThreadSafetyStatement>Gtk# is thread aware, but not thread safe; See the <link location="node:gtk-sharp/programming/threads">Gtk# Thread Programming</link> for details.</ThreadSafetyStatement>
  <Docs>
    <summary>Threads</summary>
    <remarks>
      <para>Functions for using GDK in multi-threaded programs</para>
      <para>For thread safety, Gdk relies on the thread primitives in GLib, and on the thread-safe GLib main loop.</para>
      <para>GLib is completely thread safe (all global data is automatically locked), but individual data structure instances are not automatically locked for performance reasons. So e.g. you must coordinate accesses to the same GHashTable from multiple threads.</para>
      <para>Gtk# is "thread aware" but not thread safe ? it provides a global lock controlled by <see cref="M:Gdk.Threads.Enter()" />/<see cref="M:Gdk.Threads.Leave()" /> which protects all use of Gtk. That is, only one thread can use Gtk at any given time.</para>
      <para>You must call <see cref="M:Gdk.Threads.Init()" /> before executing any other Gtk or Gdk functions in a threaded Gtk# program.</para>
      <para>Idles, timeouts, and input functions are executed outside of the main Gtk lock. So, if you need to call Gtk inside of such a callback, you must surround the callback with a <see cref="M:Gdk.Threads.Enter()" />/<see cref="M:Gdk.Threads.Leave()" /> pair. (However, signals are still executed within the main Gtk lock.)</para>
      <para>In particular, this means, if you are writing widgets that might be used in threaded programs, you must surround timeouts and idle functions in this matter.</para>
      <para>As always, you must also surround any calls to Gtk not made within a signal handler with a <see cref="M:Gdk.Threads.Enter()" />/<see cref="M:Gdk.Threads.Leave()" /> pair.
Before calling <see cref="M:Gdk.Threads.Leave()" /> from a thread other than your main thread, you probably want to call gdk_flush() to send all pending commands to the windowing system. (The reason you do not need to do this from the main thread is that GDK always automatically flushes pending commands when it runs out of incoming events to process and has to sleep while waiting for more events.)</para>
      <para>A minimal main program for a threaded GTK+ application looks like:
<example><code lang="C#">
static void Main (string[] args)
{
  Window window;

  Gdk.Threads.Init ();
  Gtk.Application.Init ();

  window = new Window ("Sample");
  window.Show ();

  Gdk.Threads.Enter ();
  Gtk.Application.Run ();
  Gdk.Threads.Leave ();

  return 0;
}
</code></example></para>
    </remarks>
  </Docs>
  <Base>
    <BaseTypeName>System.Object</BaseTypeName>
  </Base>
  <Interfaces />
  <Members>
    <Member MemberName="Leave">
      <MemberSignature Language="C#" Value="public static void Leave ();" />
      <MemberType>Method</MemberType>
      <ReturnValue>
        <ReturnType>System.Void</ReturnType>
      </ReturnValue>
      <Parameters />
      <Docs>
        <summary>Leaves a critical region begun with Gdk.Threads.Enter().</summary>
        <remarks>This marks the end of a critical section begun with Gdk.Threads.Enter.</remarks>
      </Docs>
    </Member>
    <Member MemberName="Enter">
      <MemberSignature Language="C#" Value="public static void Enter ();" />
      <MemberType>Method</MemberType>
      <ReturnValue>
        <ReturnType>System.Void</ReturnType>
      </ReturnValue>
      <Parameters />
      <Docs>
        <summary>This marks the beginning of a critical section in which Gdk and Gtk functions can be called.</summary>
        <remarks>Only one thread at a time can be in such a critial section.</remarks>
      </Docs>
    </Member>
    <Member MemberName="Init">
      <MemberSignature Language="C#" Value="public static void Init ();" />
      <MemberType>Method</MemberType>
      <ReturnValue>
        <ReturnType>System.Void</ReturnType>
      </ReturnValue>
      <Parameters />
      <Docs>
        <summary>This call must be made before any use of the main loop from Gtk#; to be safe, call it before <see cref="M:Gtk.Application.Init()" />. It must also be preceded by a call to <see cref="M:GLib.Thread.Init()" /> if GLib threading has not yet been initialized.</summary>
        <remarks>Initializes <see cref="N:Gdk" /> so that it can be used from multiple threads in conjunction with <see cref="M:Gdk.Threads.Enter()" /> and <see cref="M:Gdk.Threads.Leave()" />.</remarks>
      </Docs>
    </Member>
    <Member MemberName=".ctor">
      <MemberSignature Language="C#" Value="public Threads ();" />
      <MemberType>Constructor</MemberType>
      <ReturnValue />
      <Parameters />
      <Docs>
        <summary>The default constructor.</summary>
        <remarks />
      </Docs>
    </Member>
    <Member MemberName="AddIdle">
      <MemberSignature Language="C#" Value="public static uint AddIdle (int priority, GLib.GSourceFunc function);" />
      <MemberType>Method</MemberType>
      <ReturnValue>
        <ReturnType>System.UInt32</ReturnType>
      </ReturnValue>
      <Parameters>
        <Parameter Name="priority" Type="System.Int32" />
        <Parameter Name="function" Type="GLib.GSourceFunc" />
      </Parameters>
      <Docs>
        <param name="priority">Priority value for handler.</param>
        <param name="function">Idle callback.</param>
        <summary>Adds an idle handler.</summary>
        <returns>A source id.</returns>
        <remarks />
        <since version="Gtk# 2.12" />
      </Docs>
    </Member>
    <Member MemberName="AddTimeout">
      <MemberSignature Language="C#" Value="public static uint AddTimeout (int priority, uint interval, GLib.GSourceFunc function);" />
      <MemberType>Method</MemberType>
      <ReturnValue>
        <ReturnType>System.UInt32</ReturnType>
      </ReturnValue>
      <Parameters>
        <Parameter Name="priority" Type="System.Int32" />
        <Parameter Name="interval" Type="System.UInt32" />
        <Parameter Name="function" Type="GLib.GSourceFunc" />
      </Parameters>
      <Docs>
        <param name="priority">Priority value for handler.</param>
        <param name="interval">Timeout interval.</param>
        <param name="function">Timeout callback.</param>
        <summary>Adds a timeout handler.</summary>
        <returns>A source id.</returns>
        <remarks />
        <since version="Gtk# 2.12" />
      </Docs>
    </Member>
  </Members>
</Type>