← Back to branch summary

~ubuntu-branches/ubuntu/karmic/glib2.0/karmic-updates

« back to all changes in this revision

Viewing changes to docs/reference/glib/xml/main.xml

  • Committer: Bazaar Package Importer
  • Author(s): Martin Pitt
  • Date: 2009-07-07 08:55:47 UTC
  • mfrom: (1.2.49 upstream)
  • Revision ID: james.westby@ubuntu.com-20090707085547-oma0yur1uaq4zmop
Tags: 2.21.3-0ubuntu1
* New upstream version:
  - GMappedFile is refcounted now
  - Mainloop: It is now possible to set per-thread default contexts,
    with g_main_context_push_thread_default.
  - glib-mkenums supports a @basename@ substitution, in addition
    to @filename@.
  - GIO:
    + Vfs implementations can support storing of per-file metadata.
    + GCancellable can now be subclassed.
    + Unmount and eject methods now optionally allow interaction, via
      variants that take a GMountOperation object.
  - Bugs fixed:
   556706 Inconsistent help arguments -h, -?
   579449 FileChoosers no longer work if an idle handler is active
   579933 mainloop FD_CLOEXEC has a race condition
   579984 alternate GMainContext support
   585937 gio/gsocket.c (glib 2.21.2) does not compile (Windows/mingw)
   586675 Runtime library location
   586797 Add GCancellables to GSocket ops
   586868 g_filename_complete_get_completions doesn't always return...
   587415 g_resolver_lookup_by_name_finish returns a freed list
   587434 regression tests fail, at least on x86_64
   586928 Avoid g++ warning in g_error()
  - Updated translations: Estonian, Hebrew
* Drop 00git_file_attr_stringv.patch, in upstream release now.

Show diffs side-by-side

added added

removed removed

Lines of Context:
docs/reference/glib/xml/main.xml
91
91
<link linkend="GSource">GSource</link> *           <link linkend="g-main-current-source">g_main_current_source</link>               (void);
92
92
#define             <link linkend="g-main-set-poll-func">g_main_set_poll_func</link>                (func)
93
93
 
 
94
<link linkend="GMainContext">GMainContext</link> *      <link linkend="g-main-context-get-thread-default">g_main_context_get_thread_default</link>   (void);
 
95
<link linkend="void">void</link>                <link linkend="g-main-context-push-thread-default">g_main_context_push_thread_default</link>  (<link linkend="GMainContext">GMainContext</link> *context);
 
96
<link linkend="void">void</link>                <link linkend="g-main-context-pop-thread-default">g_main_context_pop_thread_default</link>   (<link linkend="GMainContext">GMainContext</link> *context);
 
97
 
94
98
<link linkend="GSource">GSource</link> *           <link linkend="g-timeout-source-new">g_timeout_source_new</link>                (<link linkend="guint">guint</link> interval);
95
99
<link linkend="GSource">GSource</link> *           <link linkend="g-timeout-source-new-seconds">g_timeout_source_new_seconds</link>        (<link linkend="guint">guint</link> interval);
96
100
<link linkend="guint">guint</link>               <link linkend="g-timeout-add">g_timeout_add</link>                       (<link linkend="guint">guint</link> interval,
544
548
<title>g_main_context_default ()</title>
545
549
<indexterm zone="g-main-context-default"><primary sortas="main_context_default">g_main_context_default</primary></indexterm><programlisting><link linkend="GMainContext">GMainContext</link> *      g_main_context_default              (void);</programlisting>
546
550
<para>
547
 
Returns the default main context. This is the main context used
548
 
for main loop functions when a main loop is not explicitly
549
 
specified.</para>
 
551
Returns the global default main context. This is the main context
 
552
used for main loop functions when a main loop is not explicitly
 
553
specified, and corresponds to the "main" main loop. See also
 
554
<link linkend="g-main-context-get-thread-default"><function>g_main_context_get_thread_default()</function></link>.</para>
550
555
<para>
551
556
</para><variablelist role="params">
552
 
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the default main context.
 
557
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the global default main context.
553
558
</simpara></listitem></varlistentry>
554
559
</variablelist></refsect2>
555
560
<refsect2 id="g-main-context-iteration" role="function">
1110
1115
<listitem><simpara>the function to call to poll all file descriptors.
1111
1116
</simpara></listitem></varlistentry>
1112
1117
</variablelist></refsect2>
 
1118
<refsect2 id="g-main-context-get-thread-default" role="function" condition="since:2.22">
 
1119
<title>g_main_context_get_thread_default ()</title>
 
1120
<indexterm zone="g-main-context-get-thread-default" role="2.22"><primary sortas="main_context_get_thread_default">g_main_context_get_thread_default</primary></indexterm><programlisting><link linkend="GMainContext">GMainContext</link> *      g_main_context_get_thread_default   (void);</programlisting>
 
1121
<para>
 
1122
Gets the thread-default <link linkend="GMainContext"><type>GMainContext</type></link> for this thread. Asynchronous
 
1123
operations that want to be able to be run in contexts other than
 
1124
the default one should call this method to get a <link linkend="GMainContext"><type>GMainContext</type></link> to
 
1125
add their <link linkend="GSource"><type>GSource</type></link><!-- -->s to. (Note that even in single-threaded
 
1126
programs applications may sometimes want to temporarily push a
 
1127
non-default context, so it is not safe to assume that this will
 
1128
always return <link linkend="NULL--CAPS"><literal>NULL</literal></link> if threads are not initialized.)</para>
 
1129
<para>
 
1130
</para><variablelist role="params">
 
1131
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the thread-default <link linkend="GMainContext"><type>GMainContext</type></link>, or <link linkend="NULL--CAPS"><literal>NULL</literal></link> if the
 
1132
thread-default context is the global default context.
 
1133
 
 
1134
</simpara></listitem></varlistentry>
 
1135
</variablelist><para role="since">Since 2.22</para></refsect2>
 
1136
<refsect2 id="g-main-context-push-thread-default" role="function" condition="since:2.22">
 
1137
<title>g_main_context_push_thread_default ()</title>
 
1138
<indexterm zone="g-main-context-push-thread-default" role="2.22"><primary sortas="main_context_push_thread_default">g_main_context_push_thread_default</primary></indexterm><programlisting><link linkend="void">void</link>                g_main_context_push_thread_default  (<link linkend="GMainContext">GMainContext</link> *context);</programlisting>
 
1139
<para>
 
1140
Acquires <parameter>context</parameter> and sets it as the thread-default context for the
 
1141
current thread. This will cause certain asynchronous operations
 
1142
(such as most <link linkend="gio">gio</link>-based I/O) which are
 
1143
started in this thread to run under <parameter>context</parameter> and deliver their
 
1144
results to its main loop, rather than running under the global
 
1145
default context in the main thread. Note that calling this function
 
1146
changes the context returned by
 
1147
<link linkend="g-main-context-get-thread-default"><function>g_main_context_get_thread_default()</function></link>, <emphasis>not</emphasis> the
 
1148
one returned by <link linkend="g-main-context-default"><function>g_main_context_default()</function></link>, so it does not affect the
 
1149
context used by functions like <link linkend="g-idle-add"><function>g_idle_add()</function></link>.
 
1150
</para>
 
1151
<para>
 
1152
Normally you would call this function shortly after creating a new
 
1153
thread, passing it a <link linkend="GMainContext"><type>GMainContext</type></link> which will be run by a
 
1154
<link linkend="GMainLoop"><type>GMainLoop</type></link> in that thread, to set a new default context for all
 
1155
async operations in that thread. (In this case, you don't need to
 
1156
ever call <link linkend="g-main-context-pop-thread-default"><function>g_main_context_pop_thread_default()</function></link>.) In some cases
 
1157
however, you may want to schedule a single operation in a
 
1158
non-default context, or temporarily use a non-default context in
 
1159
the main thread. In that case, you can wrap the call to the
 
1160
asynchronous operation inside a
 
1161
<link linkend="g-main-context-push-thread-default"><function>g_main_context_push_thread_default()</function></link> /
 
1162
<link linkend="g-main-context-pop-thread-default"><function>g_main_context_pop_thread_default()</function></link> pair, but it is up to you to
 
1163
ensure that no other asynchronous operations accidentally get
 
1164
started while the non-default context is active.
 
1165
</para>
 
1166
<para>
 
1167
Beware that libraries that predate this function may not correctly
 
1168
handle being used from a thread with a thread-default context. Eg,
 
1169
see <link linkend="g-file-supports-thread-contexts"><function>g_file_supports_thread_contexts()</function></link>.</para>
 
1170
<para>
 
1171
</para><variablelist role="params">
 
1172
<varlistentry><term><parameter>context</parameter>&#160;:</term>
 
1173
<listitem><simpara> a <link linkend="GMainContext"><type>GMainContext</type></link>, or <link linkend="NULL--CAPS"><literal>NULL</literal></link> for the global default context
 
1174
</simpara></listitem></varlistentry>
 
1175
</variablelist><para role="since">Since 2.22</para></refsect2>
 
1176
<refsect2 id="g-main-context-pop-thread-default" role="function" condition="since:2.22">
 
1177
<title>g_main_context_pop_thread_default ()</title>
 
1178
<indexterm zone="g-main-context-pop-thread-default" role="2.22"><primary sortas="main_context_pop_thread_default">g_main_context_pop_thread_default</primary></indexterm><programlisting><link linkend="void">void</link>                g_main_context_pop_thread_default   (<link linkend="GMainContext">GMainContext</link> *context);</programlisting>
 
1179
<para>
 
1180
Pops <parameter>context</parameter> off the thread-default context stack (verifying that
 
1181
it was on the top of the stack).</para>
 
1182
<para>
 
1183
</para><variablelist role="params">
 
1184
<varlistentry><term><parameter>context</parameter>&#160;:</term>
 
1185
<listitem><simpara> a <link linkend="GMainContext"><type>GMainContext</type></link> object, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>
 
1186
</simpara></listitem></varlistentry>
 
1187
</variablelist><para role="since">Since 2.22</para></refsect2>
1113
1188
<refsect2 id="g-timeout-source-new" role="function">
1114
1189
<title>g_timeout_source_new ()</title>
1115
1190
<indexterm zone="g-timeout-source-new"><primary sortas="timeout_source_new">g_timeout_source_new</primary></indexterm><programlisting><link linkend="GSource">GSource</link> *           g_timeout_source_new                (<link linkend="guint">guint</link> interval);</programlisting>