docs: more cleanups for GIO

Doc: Fix missing API from GOptionGroup boxing

Doc: Mark a few things as private

Win32: Move g_win32_check_windows_version() to the correct place in header

It was added after G_END_DECLS, outside the #ifdef G_PLATFORM_WIN32,
and inside a #ifndef __GTK_DOC_IGNORE__ block. So it was missing from
the doc.

https://bugzilla.gnome.org/show_bug.cgi?id=743661

Updated Latvian translation

Updated Korean translation

Updated Greek translation

Update Catalan translation

Updated German translation

Updated POTFILES.in

gtask: Add a GTask:completed property

This can be used to query whether the task has completed, in the sense
that it has had a result set on it, and has already – or will soon –
invoke its callback function.

Notifications for this property are emitted immediately after the task’s
main callback, in the same main context as that callback. This allows
for multiple bits of code to listen for completion of the GTask, which
opens the door for blocking on cancellation of the GTask and improved
handling of ‘pending’ behaviour.

https://bugzilla.gnome.org/show_bug.cgi?id=743636

Updated Bulgarian translation

Updated Slovak translation

Updated Vietnamese translation

Signed-off-by: Trần Ngọc Quân <vnwildman@gmail.com>

Updated Spanish translation

Updated Lithuanian translation

Updated Kazakh translation

Updated Hungarian translation

Updated Italian translation

Updated Polish translation

Updated POTFILES.in

Updated Korean translation

GSocketClient: fix handling of application proxies

g_socket_client_add_application_proxy() claimed "When the indicated
proxy protocol is returned by the #GProxyResolver, #GSocketClient will
consider this protocol as supported but will not try to find a #GProxy
instance to handle handshaking." But in fact, it did the checks in the
wrong order, so GProxy proxies ended up overriding
application-specified ones. Fix that.

Also, simplify the code a bit by making use of g_hash_table_add() and
g_hash_table_contains().

https://bugzilla.gnome.org/show_bug.cgi?id=733876

HTTP proxy support

Based on code from "WockyHttpProxy" written by Nicolas Dufresne
and Marc-André Lureau. Initial glib patch by Brian J. Murrell.

https://bugzilla.gnome.org/show_bug.cgi?id=733876

Windows: Use Standard Networking Functions If Possible

Currently, the Windows code use Winsock2-specific APIs to try to emulate
calls such as inet_pton(), inet_ntop() and if_nametoindex(), which may not
do the job all the time.  On Vista and later, Winsock2 does provide a
proper implementation for these functions, so we can use them if they exist
on the system, by querying for them during g_networking_init().  Otherwise,
we continue to use the original code path for these, in the case of XP and
Server 2003.

This enables many of the network-address tests to pass on Windows as a
result, when the native Winsock2 implementations can be used.

https://bugzilla.gnome.org/show_bug.cgi?id=730352

gfdonotificationbackend: support themed icons

The spec allows setting the "image-path" hint to an icon name as well.

https://bugzilla.gnome.org/show_bug.cgi?id=745634

gresolver.c: Windows: Fix IPv6 Address Handling

Check the IPv6 addresses on Windows, as we need to reject those that have
brackets/ports around them as valid addresses in this form would have been
accepted during the call to g_inet_address_new_from_string ().

https://bugzilla.gnome.org/show_bug.cgi?id=730352

gio: add some missing autocleanup

https://bugzilla.gnome.org/show_bug.cgi?id=745589

Signed-off-by: Marc-Antoine Perennou <Marc-Antoine@Perennou.com>

MSVC Builds: Few More Enahncements

Update the .pdb file generation for the MSVC 2010+ DLLs (and the x64 gspawn
helper programs), so that they match the names of the DLLs/EXEs that are
built.  Also update the .lib generation so that all will use -$(ApiVersion)
from the property sheets instead of the -2.0 which was previously hard
coded (as we will eventually move into GLib 3.x in the future, for example)

gobject: Mark a helper variable as const

It’s only used for argv values, which are not modified here.

https://bugzilla.gnome.org/show_bug.cgi?id=614684

gerror: Minor clarifications to the GError documentation

 • Clarify that GError** parameters are for the return of _newly
   allocated_ GError*s.
 • Clarify that errors may need to be checked for explicitly if the
   return value of a function doesn’t reliably indicate them.

https://bugzilla.gnome.org/show_bug.cgi?id=741779

Updated Serbian translation

gvariant: Use ‘UTF-8’ in docs rather than ‘utf8’

Nitpicky correction.

https://bugzilla.gnome.org/show_bug.cgi?id=741779

gmain: Explicitly document the threading behaviour of g_timeout_add()

i.e. That calling g_timeout_add() from a thread other than the main one
probably doesn’t do what you want. Same for g_idle_add() and the
*_full() variants.

https://bugzilla.gnome.org/show_bug.cgi?id=741779

gobject: Mention g_clear_object() in g_object_unref() documentation

https://bugzilla.gnome.org/show_bug.cgi?id=741779

gmem: Clarify that a NULL check is not needed before calling g_free()

It was documented before, but wasn’t especially clear. Doing
    if (X)
        g_free (X);
is apparently quite a pervasive real-world anti-pattern, so perhaps it
could be documented more explicitly.

https://bugzilla.gnome.org/show_bug.cgi?id=741779

glist: Clarify that g_list_nth() is expensive

Just in case people have forgotten their basic algorithms course. Seen
in some pretty terrible code in the wild; hopefully mentioning the cost
in the documentation will make people think twice about using a counter
variable when iterating over a linked list.

https://bugzilla.gnome.org/show_bug.cgi?id=741779

glist: Clarify how g_list_free_1() handles links

It doesn’t, which is fine, but could be unexpected if undocumented.

https://bugzilla.gnome.org/show_bug.cgi?id=741779

ghash: Document that g_hash_get_[keys|values]() are expensive

And definitely not the right way to iterate over a hash table (as seen
in code in the wild).

https://bugzilla.gnome.org/show_bug.cgi?id=741779

gparamspecs: Recommend use of most specific GParamSpec types

It’s quite common to see a g_param_spec_pointer() used for GObject or
boxed types which, while not incorrect, does make memory management
unsafe, since no copying or reference counting can be performed
automatically.

Similarly, people often use g_param_spec_boolean() when an enum would be
more appropriate, cf.
    http://blog.ometer.com/2011/01/20/boolean-parameters-are-wrong/
Using enums also means that the set of allowable values can be extended
in future if needed.

In the hope that people who write code like that read the documentation,
mention the more specific types in the documentation.

https://bugzilla.gnome.org/show_bug.cgi?id=741779

docs: Expand introduction to mention using async calls over sync ones

As discussed on the mailing list (see the whole thread):
    https://mail.gnome.org/archives/desktop-devel-list/2015-February/msg00126.html

Expand the GIO documentation introduction to talk a little about when to
use async and sync functions, and how the former should almost always be
preferred over the latter.

Link to this from the GFile documentation, which is an entry point for a
lot of async calls.

https://bugzilla.gnome.org/show_bug.cgi?id=744722

gstring: Mark the return value from g_string_free() as nullable

It’s NULL iff free_segment is TRUE, so the annotation doesn’t quite
capture all the function definition, but is a safe over-estimate of the
return value’s nullability.

https://bugzilla.gnome.org/show_bug.cgi?id=719966

gfileutils: Mark the return value from g_path_skip_root() as nullable

It returns NULL for non-absolute paths.

https://bugzilla.gnome.org/show_bug.cgi?id=719966

docs: Remove redundant header examples from GObject tutorial

These are in the header boilerplate section, but are actually source
boilerplate which is covered in later sections.

https://bugzilla.gnome.org/show_bug.cgi?id=744060

docs: Change tutorial encodings from ISO-8859-1 to UTF-8

ISO-8859-1 — that’s a blast from the past.

https://bugzilla.gnome.org/show_bug.cgi?id=744060

Visual Studio Builds: "Install" .pdb files

They are helpful in debugging in a stack.

MSVC Builds: GIO: Standardize zlib Linking

Link to zlib1.lib for all builds, as:
-The notion of zlib1d.lib is rather not standardized across the board for
 most cases.
-Easier for the grand all-in-one solution file.

Visual Studio 2008 Builds: Speed Up Release Builds

Use the /MP option so that each project can build multiple sources in
parallel, which can cut down release build times by quite a bit.  This will
cause a brief warning for debug builds due to their use of /Gm, and builds
would otherwise proceed as they did before.

Unfortunately Visual Studio 2008 is too old to support the /d2Zi+ flag, so
we can't make a better debug situation for it at the moment.

MSVC Builds: Improve Build Speed and Debugging

Use Multiprocessor compilation which can cut down build times by quite a
bit and use the /d2Zi+ flag to have better debugging info being logged to
the .pdb for release builds.

These are only applicable for Visual Studio 2010/2012 and later.

MSVC Builds: Fix and Update "Installation"

The gobjectnotifyqueue.c was accidently dropped from the files to copy, and
a new public header for GIO was added, so address these parts.

Updated Czech translation

GContextSpecificGroup: fix deadlock

There was a theoretical deadlock between the worker trying to emit a
signal at the same time as we were waiting for it to shutdown the
notification (while holding the lock).

The deadlock was particularly annoying because we didn't really need to
wait for the shutdown and because it wasn't possible to signals to
arrive while waiting for a start.  Attempting to deal with start and
stop in an asymmetric way could have lead to other weird situations,
however.

Drop the lock while waiting for the worker thread to start.  This means
that we face the possibility of multiple waiters on the cond at the same
time, so we need to make more of a state machine.

https://bugzilla.gnome.org/show_bug.cgi?id=742599

tests: add some tests for GContextSpecificGroup

https://bugzilla.gnome.org/show_bug.cgi?id=742599

Make GUnixMountMonitor per-context

GUnixMountMonitor was not threadsafe before.  It was a global singleton
which emitted signals in the first thread that happened to construct it.

Move it to a per-context singleton model where each GMainContext gets
its own GUnixMountMonitor.  Monitor for the changes from the GLib worker
thread and dispatch the results to each context with an active monitor.

https://bugzilla.gnome.org/show_bug.cgi?id=742599

gunixmounts: move GUnixMountMonitor code

Move this code to the correct part of the file.

While we're at it, drop an unused #define MOUNT_POLL_INTERVAL.

https://bugzilla.gnome.org/show_bug.cgi?id=742599

gunixmounts.c: add fold markers

This is a large file with a lot of very complicated code in it.  Add
some fold markers to make things a bit more manageable.

https://bugzilla.gnome.org/show_bug.cgi?id=742599

Deprecate g_unix_mount_monitor_set_rate_limit()

Deprecate g_unix_mount_monitor_set_rate_limit() and turn it into a
no-op.

This function doesn't behave as advertised.  It only controls rate
limiting for filesystem-based monitors.  It has no impact over reporting
mount changes on Linux, for example, because those are based on polling
for changes in /proc (which doesn't use filesystem monitors).  It also
has no impact on Mac OS because a library interface is used there.

This was added in https://bugzilla.gnome.org/show_bug.cgi?id=521946 in
order to be used by HAL, which is effectively dead.  udisks no longer
uses this code at all.

https://bugzilla.gnome.org/show_bug.cgi?id=742599

Rename g_unix_mount_monitor_new() to _get()

This is a singleton, but we have a function called _new() to get it.
What's worse is that the documentation makes no mention of this, and
actually specifically says that a new monitor will be created each time.

https://bugzilla.gnome.org/show_bug.cgi?id=742599

GAppInfoMonitor: port to GContextSpecificGroup

https://bugzilla.gnome.org/show_bug.cgi?id=742599

Add internal helper GContextSpecificGroup

Add a new internal helper called GContextSpecificGroup.

This is a mechanism for helping to maintain a group of context-specific
monitor objects (eg: GAppInfoMonitor, GUnixMountMonitor).

https://bugzilla.gnome.org/show_bug.cgi?id=742599

Updated Polish translation

GLib 2.43.91

GApplication: don't iterate further on _quit()

If someone explicitly calls g_application_quit() then don't attempt to
drain the mainloop of remaining sources.

This allows applications with 100% CPU utilisation to quit reliably.

https://bugzilla.gnome.org/show_bug.cgi?id=744876

gio: Add some missing type annotations to object arguments

Similar to https://bugzilla.gnome.org/show_bug.cgi?id=745239

tests: only chmod autorun.exe on UNIX

We install win32-software/autorun.exe (as test data for mime scanning)
only on UNIX builds, so don't attempt to chmod it on 'make install'
unless we're on UNIX.

Updated Lithuanian translation

Updated Slovak translation

make *_get_instance_private const-compliant

This is pure read-only access to an external struct
so void warnings for people calling it from const
contexts such as accessors

https://bugzilla.gnome.org/show_bug.cgi?id=745068

Signed-off-by: Marc-Antoine Perennou <Marc-Antoine@Perennou.com>

G_DECLARE_*: be const-compliant

switching to the old macros boilerplate to G_DECLARE_*
a lot of warnings start to pop when *_IS_A_* or such are
called from a const context.
Fix this by taking const pointers as parameters

https://bugzilla.gnome.org/show_bug.cgi?id=745068

Signed-off-by: Marc-Antoine Perennou <Marc-Antoine@Perennou.com>

GPropertyAction: add type annotation to constructor's object argument

https://bugzilla.gnome.org/show_bug.cgi?id=745239

gobject.h: Use correct format specifier for __LINE__

GCC 5.0, with its new -Wformat-signedness, warns about the sign being
different between a type and the format string in printf-format
messages, leading to compiler warnings with G_OBJECT_WARN_INVALID_PSPEC.
In other uses of __LINE__ inside GLib, %d is used, and GCC seems to
expect a format specifier of %d as well:
https://gcc.gnu.org/onlinedocs/cpp/Standard-Predefined-Macros.html

https://bugzilla.gnome.org/show_bug.cgi?id=744263

gcancellable: Mention nullability in g_cancellable_cancel() docs

Calling g_cancellable_cancel(NULL) is an explicitly allowed no-op, for
convenience. Document and annotate that.

Updated French translation

tests: Add many autoptr tests

I love Emacs keyboard macros, used them to convert the list of
defines cleverly into a list of tests, then iterated and filled in
the necessary constructor arguments.

autocleanups: Remove g_autoptr(gchar)

- It's not sufficient, there are other bare array types
  like guint8, gdouble, etc.

- Other types like GVariant* always come as pointers, whereas
  there's a rather fundamental distinction between "gchar" and
  "gchar*" that has been signified to C programmers for 30+ years via
  the '*' character, and we're hiding that.

https://bugzilla.gnome.org/show_bug.cgi?id=744747

Add g_autofree

The g_autoptr() being associated with the type name works out really
well for things like GHashTable.  However, it's a bit more awkward to
associate with "gchar".  Also because one can't use "char".
Similarly, there are a lot of other "bare primitive array" types that
one might reasonably use.

This patch does not remove the autoptr for "gchar", even though I
think it's rather awkward and strange.

Also while we're here, add a test case for the cleanup bits.

https://bugzilla.gnome.org/show_bug.cgi?id=744747

GApplication: let the main loop drain on shutdown

After ::shutdown, run the mainloop until all pending activity is
handled, before returning from run().

Among other things, this gives a chance for destroyed windows to be
properly withdrawn from the windowing system.

https://bugzilla.gnome.org/show_bug.cgi?id=744876

Updated Chinese (Taiwan) translation

gobject: Add missing autocleanup for GInitiallyUnowned

We are missing the auto cleanup function for this type, which means
G_DECLARE_* macros won't work with classes inheriting from
GInitiallyUnowned.

gfileenumerator: Convert docbook tag -> markdown

This code predated the markdown conversion.  Pointed out by mclasen.

filenumerator: Add g_file_enumerator_iterate()

This is *significantly* more pleasant to use from C (while handling
errors and memory cleanup).

While we're here, change some ugly, leaky code in
tests/desktop-app-info.c to use it, in addition to a test case
in tests/file.c.

https://bugzilla.gnome.org/show_bug.cgi?id=661554

autocleanups: Add G*Array types

Not sure how these were omitted.  Probably few people are really using
this yet...and we don't have test cases (that's in the other patch).

https://bugzilla.gnome.org/show_bug.cgi?id=744830

gliststore: Add missing parameter documentation

Updated Galician translations

gapplication: test setting and binding busy state

https://bugzilla.gnome.org/show_bug.cgi?id=744756

gapplication: add "is-busy"

A property to query the current busy state of an application.

https://bugzilla.gnome.org/show_bug.cgi?id=744756

gapplication: stop using deprecated API

More fallout from the GOptionGroup binding patch.

gapplication: tune busy-binding

g_application_bind_busy_property() had the restriction that only one
property can be bound per object, so that NULL could be used to unbind.
Even though this is enough for most uses, it is a weird API.

Lift that restriction and add an explicit unbind function.

https://bugzilla.gnome.org/show_bug.cgi?id=744565

GLib 2.43.90

Updated POTFILES.in

Updated Italian translation

tests: add GSimpleIOStream async close tests

Just a couple of tests to make sure the two paths are working properly,
without crashes or leaks.

https://bugzilla.gnome.org/show_bug.cgi?id=741630

Add GSimpleIOStream class

GSimpleIOStream represents an object that wraps an input and an output
stream making easy to use them by calling the #GIOStream methods.

https://bugzilla.gnome.org/show_bug.cgi?id=741630

GIOStream: support for unemulated async close()

Add an implementation of non-thread-emulated async close of a GIOStream
if either of the underlying stream objects support it.

This prevents us from calling close() functions from another thread on
an object that may not be expecting that.  It also allows us to skip the
thread entirely in case our objects support a pure async close.

https://bugzilla.gnome.org/show_bug.cgi?id=741630

streams: add private 'async close via threads' API

Add an internal helper to find out if close_async() is implemented via
threads using the default implementation in the base class.

We will use this to decide if we should do a 'pure async' close of a
GIOStream or not.

https://bugzilla.gnome.org/show_bug.cgi?id=741630

streams: de-gtkdocify internal API

Remove the /** **/-style block from two internal helpers to prevent
gtk-doc from picking them up.

https://bugzilla.gnome.org/show_bug.cgi?id=741630

gdbus: delay closing stream after read finish

Closing the stream on the writing side my race with a pending read. This
patch ensures that closing is delayed after reading is finished.

https://bugzilla.gnome.org/show_bug.cgi?id=743990

tests: check for NULL before g_object_unref()

delayed_close_free() calls g_object_unref() on a variable that is
expected to possibly contain NULL (as indicated by the fact that the
NULL case is handled in my_slow_close_output_stream_close_async()).

This is dead code right now (due to a bug in GDBus), which is why it
isn't actually causing a failure.  It should still be fixed, however.

https://bugzilla.gnome.org/show_bug.cgi?id=743990

autocleanups: Use g_option_context_unref()

This fixes a use of a deprecated API.

gapplication: never set the prgname to the app id

GApplication set the prgname to the application's id when it was running
in service mode. This broke with the addition of new --app-id option,
because g_set_prgname() was called before parsing the options. Calling
it after option parsing doesn't work, because GOptionContext sets
prgname to argv[0] unconditionally.

Instead of changing the semantics of GOptionContext, simply remove this
functionality from GApplication. It is very unusual to have the prgname
set to the app id instead of the binary's name and might confuse people
when looking at logs etc.

When overriding local_command_line() from a subclass,
g_option_context_parse() might never be invokded. Thus, continue setting
the prgname to argv[0] in GApplication.

https://bugzilla.gnome.org/show_bug.cgi?id=743933