==1265== 84 (8 direct, 76 indirect) bytes in 1 blocks are definitely lost in loss record 793 of 827
==1265== at 0x4029467: calloc (vg_replace_malloc.c:467)
==1265== by 0x408479B: standard_calloc (gmem.c:104)
==1265== by 0x4084846: g_malloc0 (gmem.c:189)
==1265== by 0x4084B2D: g_malloc0_n (gmem.c:385)
==1265== by 0x4228A98: g_resource_load (gresource.c:253)
==1265== by 0x804A56D: test_resource_registred (resources.c:198)
==509== 700 (20 direct, 680 indirect) bytes in 1 blocks are definitely lost in loss record 828 of 837
==509== at 0x402AD89: malloc (vg_replace_malloc.c:236)
==509== by 0x4084724: standard_malloc (gmem.c:85)
==509== by 0x40847C7: g_malloc (gmem.c:159)
==509== by 0x409B1E1: g_slice_alloc (gslice.c:1003)
==509== by 0x405396B: g_bytes_new_with_free_func (gbytes.c:173)
==509== by 0x405390D: g_bytes_new_take (gbytes.c:122)
==509== by 0x804A48C: test_resource_data (resources.c:174)
==29204== 11,456 (84 direct, 11,372 indirect) bytes in 1 blocks are definitely lost in loss record 859 of 861
==29204== at 0x402AD89: malloc (vg_replace_malloc.c:236)
==29204== by 0x4084724: standard_malloc (gmem.c:85)
==29204== by 0x40847C7: g_malloc (gmem.c:159)
==29204== by 0x409B1E1: g_slice_alloc (gslice.c:1003)
==29204== by 0x409B227: g_slice_alloc0 (gslice.c:1029)
==29204== by 0x41936CF: g_type_create_instance (gtype.c:1872)
==29204== by 0x417CCC9: g_object_constructor (gobject.c:1839)
==29204== by 0x417C6F4: g_object_newv (gobject.c:1703)
==29204== by 0x417CC5A: g_object_new_valist (gobject.c:1820)
==29204== by 0x417C1DB: g_object_new (gobject.c:1535)
==29204== by 0x41E5E29: g_converter_input_stream_new (gconverterinputstream.c:204)
==29204== by 0x4228D38: g_resource_open_stream (gresource.c:363)
==28778== 700 (20 direct, 680 indirect) bytes in 1 blocks are definitely lost in loss record 842 of 863
==28778== at 0x402AD89: malloc (vg_replace_malloc.c:236)
==28778== by 0x4084724: standard_malloc (gmem.c:85)
==28778== by 0x40847C7: g_malloc (gmem.c:159)
==28778== by 0x409B1E1: g_slice_alloc (gslice.c:1003)
==28778== by 0x405396B: g_bytes_new_with_free_func (gbytes.c:173)
==28778== by 0x405390D: g_bytes_new_take (gbytes.c:122)
==28778== by 0x804C2B1: test_uri_query_info (resources.c:435)
==28318== 38 (12 direct, 26 indirect) bytes in 1 blocks are definitely lost in loss record 613 of 865
==28318== at 0x402AD89: malloc (vg_replace_malloc.c:236)
==28318== by 0x4084724: standard_malloc (gmem.c:85)
==28318== by 0x40847C7: g_malloc (gmem.c:159)
==28318== by 0x4084AB4: g_malloc_n (gmem.c:361)
==28318== by 0x4229599: g_resources_enumerate_children (gresource.c:806)
==28318== by 0x804B39E: test_resource_registred (resources.c:283)
==27820== 31 bytes in 1 blocks are definitely lost in loss record 587 of 866
==27820== at 0x402AD89: malloc (vg_replace_malloc.c:236)
==27820== by 0x4084724: standard_malloc (gmem.c:85)
==27820== by 0x40847C7: g_malloc (gmem.c:159)
==27820== by 0x4084AB4: g_malloc_n (gmem.c:361)
==27820== by 0x409D6A1: g_strdup (gstrfuncs.c:356)
==27820== by 0x4069FF7: g_get_current_dir (gfileutils.c:2544)
==27820== by 0x804BCA7: test_resource_module (resources.c:370)
The glib-compile-resources --generate-dependencies call was failing,
although not stopping the build.
Failed to open file 'test2.gresource.xml': No such file or directory
Failed to open file 'test3.gresource.xml': No such file or directory
Failed to open file 'test4.gresource.xml': No such file or directory
Failed to open file 'test.gresource.xml': No such file or directory
With this we're not longer exporting the constructor headers, which means
we're not tying ourselves to a macro that might need special tweaking on
a compiler-by-compiler basis.
It's hardly useful to bloat the resource data with blanks intended only
for human readability, so add a preprocessing option that uses xmllint --noblanks
to strip these.
Bug #667929.
struct sin6_addr has two additional fields that struct sin_addr
doesn't. Add support for those to GInetSocketAddress, and make sure
they don't get lost when converting between glib and native types.
https://bugzilla.gnome.org/show_bug.cgi?id=635554
Some of the GLib tests deliberately provoke warnings (or even fatal
errors) in a forked child. Normally, this is fine, but under valgrind
it's somewhat undesirable. We do want to follow fork(), so we can check
for leaks in child processes that exit gracefully; but we don't want to
be told about "leaks" in processes that are crashing, because there'd
be no point in cleaning those up anyway.
https://bugzilla.gnome.org/show_bug.cgi?id=666116
This can be used for debugging, or for progress UIs ("Connecting to
example.com..."), or to do low-level tweaking on the connection at
various points in the process.
https://bugzilla.gnome.org/show_bug.cgi?id=665805
g_main_loop_quit() only quits mainloops that are currently running --
not ones that may run in the future. The way the gdbus-threading tests
are written can possibly result in a call to g_main_loop_quit() before
g_main_loop_run() has started.
The mainloops aren't actually used for anything other than signalling
the completion of the threads, so just use g_thread_join() for that.
https://bugzilla.gnome.org/show_bug.cgi?id=666129
Have one simple _get() API that returns the group immediately, in an
empty state. The group is initialised on the first attempt to interact
with it.
Leave a secret 'back door' for GApplication to do a blocking
initialisation.
GDBusConnection now dispatches GDestroyNotify calls back to the
mainloop. Adding an idle to the mainloop is O(n) in the number of idles
already there. We therefore need to periodically empty the mainloop to
avoid quadratic behaviour with a very large 'n'.
Exporting can only be done relative to a particular given main context
and all interaction with the action group must be on that same context.
Fix up the implementation so that the user can specify that context with
the normal (thread default) mechanism and document the limitation on the
API.
Adjust the testcase to adhere to the documentation limitations. It
passes now.
Sometimes randa and randb end up having the same state, causing them to
return the same stream of 'random numbers'. This is a problem for the
testcase that is looping to find unequal menus.
If we find ourselves in this state, throw one of the random generators
away and recreate it so we have a better chance of getting some unequal
menus.
Give it the same treatment as the exporter for GActionGroup just got.
There is a wart here: the exporter attempt to re-enter GDBusConnection
when it is freed in order to cancel outstanding name watches.
GDBusConnection holds its own lock while calling the destroy notify, so
the attempt at reentrancy results in a deadlock.
We have a workaround to deal with that for now...
Rename g_application_set_menu to g_application_set_app_menu and make a
couple of fixups. Clarify the documentation about exactly what this
menu is meant to be.
Add g_application_set_menubar and document that as well.
Create a 'mirror' model of the proxy for the testcase. In addition to
testing that the proxy model emits the proper signals this also keeps
the proxy alive (by holding references to it from the mirror).
The previous code would create the submenu proxies and destroy them
right away (from the recursive step in the equality comparison
functions). This means that the subscription would go out over D-Bus
and the proxy would be destroyed before it returned. Keeping the model
alive allows it to be actually updated.
Each test needs to remove the sources that it attaches
to the default main context, or else things will work
fine in isolation, but go bad in a full test run.
There are no public 'exporter' objects, so don't allude to them
in the function names. At the same time, we want to make it clear
that these functions are D-Bus specific.
The new APIs are
g_action_group_dbus_export_start
g_action_group_dbus_export_query
g_action_group_dbus_export_stop
g_menu_model_dbus_export_start
g_menu_model_dbus_export_query
g_menu_model_dbus_export_stop
This is useful in peer-to-peer connections.
With minor changes by David Zeuthen <davidz@redhat.com>.
https://bugzilla.gnome.org/show_bug.cgi?id=662718
Signed-off-by: David Zeuthen <davidz@redhat.com>
A g_input_stream_read_async() implementation can't call
g_input_stream_read() on itself directly because it will fail because
the pending flag is already set. So fix that by invoking the vmethod
directly rather than calling the wrapper. Likewise with
GMemoryOutputStream.
Add a test to gio/tests/memory-input-stream.c to catch read_async
failures in the future.
If we can't get on the session bus, just behave like a normal non-unique
application.
This turns out to be remarkably easy to implement and lets us avoid
adding a 'dummy' backend.
Add a test for this case as well.
Idea from Zachary Dovel.
https://bugzilla.gnome.org/show_bug.cgi?id=651997
These might even make useful public API if they grew a Windows
implementation, but for now they can be Unix-only test API.
Bug: https://bugzilla.gnome.org/show_bug.cgi?id=662395
Signed-off-by: Simon McVittie <simon.mcvittie@collabora.co.uk>
Reviewed-by: Cosimo Alfarano <cosimo.alfarano@collabora.co.uk>
PKCS#8 is the "right" way to encode private keys. Although the APIs do
not currently support encrypted keys, we should at least support
unencrypted PKCS#8 keys.
https://bugzilla.gnome.org/show_bug.cgi?id=664321
Any method that has its prefix'd argument as its first parameter will be
interpreted by introspection as a method. We don't want this, so we need
to swap the first two parameters.
Previously, if you created a GUnixInputStream or GUnixOutputStream
from a non-blocking file descriptor, it might sometimes return
G_IO_ERROR_WOULD_BLOCK from g_input_stream_read/g_output_stream_write,
which is wrong. Fix that. (Use the GPollableInput/OutputStream methods
if you want non-blocking I/O.)
Also, add a test for this to gio/tests/unix-streams.
Also, fix the GError messages to say "Error reading from file
descriptor", etc instead of "Error reading from unix" (which was
presumably from a bad search and replace job).
https://bugzilla.gnome.org/show_bug.cgi?id=626866
Add GNetworkMonitor and its associated extension point, provide a base
implementation that always claims the network is available, and a
netlink-based implementation built on top of that that actually tracks
the network state.
https://bugzilla.gnome.org/show_bug.cgi?id=620932
We didn't previously test anything except the implicit default of TRUE.
Now we test implicit TRUE, explicit TRUE, explicit FALSE, and
disconnecting at the local end (which regressed while fixing Bug #651268).
Also avoid some questionable use of a main context, which fell foul of
Bug #658999 and caused this test to be disabled in master.
Bug: https://bugzilla.gnome.org/show_bug.cgi?id=662100
Bug-NB: NB#287088
Signed-off-by: Simon McVittie <simon.mcvittie@collabora.co.uk>
Reviewed-by: David Zeuthen <davidz@redhat.com>
GDBusConnection sets the closed flag in the worker thread, then adds an
idle callback (which refs the Connection) to signal this in the main
thread. The tests session_bus_down doesn't spin the mainloop, so the
"closed" signal will always fire if iterating the mainloop later (and
drops the ref when doing so). But _is_closed can return TRUE even before
signalling this, in which case the "closed" signal isn't fired and the
ref isn't dropped, causing the test to fail.
Instead simply always wait for the closed signal, which is a good thing
to check anyway and ensures the ref is closed.
Bug: https://bugzilla.gnome.org/show_bug.cgi?id=661896
Reviewed-by: Matthias Clasen <mclasen@redhat.com>
And remove the 'joinable' argument from g_thread_new() and
g_thread_new_full().
Change the wording in the docs. Clarify expectations for
(deprecated) g_thread_create().
If the connection to the bus is lost while a method call is ongoing,
the method call does not get cancelled. Instead it just sits around
until it times out.
This is visible here on XO laptops when stopping the display manager
during shutdown. imsettings starts sending a sync message to give up
its bus name (via g_bus_unown_name()), then systemd terminates the
session bus at approximately the same time. imsettings then hangs for
about 20 seconds before timing out the message.
http://lists.freedesktop.org/archives/dbus/2011-September/014717.html
imsettings behaviour could be improved as described in that thread,
but I think this is a glib bug. I've also come up with the attached
patch which fixes it.
Credits for the bug-fix goes to Daniel Drake <dsd@laptop.org>. The test
case was written by David Zeuthen <zeuthen@gmail.com>.
https://bugzilla.gnome.org/show_bug.cgi?id=660637
Signed-off-by: David Zeuthen <davidz@redhat.com>
Since it is valid for a D-Bus interface / service to add new methods,
signals or properties we must NEVER warn about unknown properties or
drop unknown signals or disallow unknown method invocations when we
have an expected interface.
So this means that the expected_interface machinery is only useful for
checking that the service didn't break ABI.
Also update the docs so it is clear exactly what it means to have an
expected interface.
https://bugzilla.gnome.org/show_bug.cgi?id=660886
Signed-off-by: David Zeuthen <davidz@redhat.com>
These were the last users of the dynamic allocation API.
Keep the uses in glib/tests/mutex.c since this is actually meant to test
the API (which has to continue working, even if it is deprecated).
https://bugzilla.gnome.org/show_bug.cgi?id=660739
This reverts commit c841c2ce3f.
This approach has been an unmitigated disaster. We're getting all sorts
of crashes due to functions that are returning NULL because they can't
find the schema for the default value. The people who get these crashes
are then confused about the root cause of the problem and waste a lot of
time trying to figure it out.
Until we find a better solution, we should go back to what we had
before.
https://bugzilla.gnome.org/show_bug.cgi?id=655366
This tests the interaction between mimeinfo.cache, defaults.list and
mimeapps.list to ensure g_app_info_set_as_last_used_for_type doesn't
incorrectly change the default.
https://bugzilla.gnome.org/show_bug.cgi?id=658188
The documentation for G_TYPE_CHAR says:
"The type designated by G_TYPE_CHAR is unconditionally an 8-bit signed
integer."
However the return value for g_value_get_char() was just "char" which
in C has an unspecified signedness; on e.g. x86 it's signed (which
matches the GType), but on e.g. PowerPC or ARM, it's not.
We can't break the old API, so we need to suck it up and add new API.
Port most internal users, but keep some tests of the old API too.
https://bugzilla.gnome.org/show_bug.cgi?id=659870
The GApplication test case tried to fork() while using GMainLoop,
causing problems. Avoid doing that by splitting the child process into
a separate program and spawning it in the usual way.
https://bugzilla.gnome.org/show_bug.cgi?id=658999
In particular, remove the libasyncns import, which was only used by
GUnixResolver, which is only used when threads are not available.
Likewise remove GWin32Resolver, and the hacky broken non-threaded
parts of GIOScheduler.
https://bugzilla.gnome.org/show_bug.cgi?id=616754
The threaded tests are using the default main context in the worker
thread, but were not g_main_context_acquire()ing it first, which meant
that g_tls_interaction_invoke_ask_password() in the main thread would
sometimes succeed in acquiring it itself and thus performing the
operation in the wrong thread. Fix that.
Also, we can't unref the loop from the worker thread, because the main
thread isn't holding a reference on it, and so it might end up being
destroyed while that thread is still inside g_main_loop_quit().
(which shouldn't ever have been part of the API. Grr.)
Solaris /etc/services doesn't even have "http", which was causing
tests/network-address to fail...
* Add 'invoke' style method, which can be used to call an interaction
from any thread. The interaction will be run in the appropriate
#GMainContext
* Sync methods can be called whether main loop is running or not.
* Derived classes can choose to implement only sync or async
interaction method, and the invoke method will fill in the blanks.
* Documentation for the above.
* Tests for the above.
https://bugzilla.gnome.org/show_bug.cgi?id=657567
The test was using a socket in a temporary directory, but not actually
creating that temporary directory. This worked fine on Linux since it
actually ended up using an abstract socket instead, but failed on
unixes without abstract sockets.
https://bugzilla.gnome.org/show_bug.cgi?id=657517
The docs for g_socket_set_timeout() claimed that if an async operation
timed out, the GIOCondition passed to the source callback would be
G_IO_IN or G_IO_OUT (thus prompting the caller to call
g_socket_receive/send and get a G_IO_ERROR_TIMED_OUT), but in fact it
ended up being 0, and gio/tests/socket.c was erroneously testing for
that instead of the correct value. Fix this.
* Add cancellable argument to g_tls_interaction_ask_password
and g_tls_interaction_ask_password_async.
* This is API breakage, but this API has not yet been released
in a stable release (and very unlikely used yet).
* Since we're breaking unreleased API, expand amount of padding
on GTlsInteractionClass because we're going to need it.
https://bugzilla.gnome.org/show_bug.cgi?id=656443
Rework property getters to use a vfunc so we can take the fast path
and avoid allocating memory for both the skeleton and the proxy
cases. This requires some special case because of how GVariant expects
you to free memory in some cases, see #657100. Add test cases for
this.
Document the _get_ functions as not being thread-safe and also
generate _dup_ C getters (which are thread-safe).
Mark all the generated _get_, _dup_ and _set_ as (skip) as non-C
languages should just use GObject properties and not the (socalled)
"C binding".
Signed-off-by: David Zeuthen <davidz@redhat.com>
* Update documentation to note that GCancellable can be used
concurrently by multiple operations.
* Add documentation to g_cancellable_reset that behavior is
undefined if called from within cancelled handler.
* Add test for multiple concurrent operations using the same
cancellable.
https://bugzilla.gnome.org/show_bug.cgi?id=656387
Destroying a GDBusProxy in a thread used to race with NameOwnerChanged
being delivered to the main context's thread (GNOME #651133).
Also, g_dbus_proxy_call_sync in a thread would race with NameOwnerChanged
being delivered to the main context's thread and rewriting the name_owner
(GNOME #656039).
Bug: https://bugzilla.gnome.org/show_bug.cgi?id=656039
Bug-NB: NB#259760
Signed-off-by: Simon McVittie <simon.mcvittie@collabora.co.uk>
Signed-off-by: David Zeuthen <davidz@redhat.com>
The database is an abstract object implemented by the various TLS
backends, which is used by GTlsConnection to lookup certificates
and keys, as well as verify certificate chains.
Also add GTlsInteraction, which can be used to prompt the user
for a password or PIN (used with the database).
https://bugzilla.gnome.org/show_bug.cgi?id=636572
Otherwise, we may run into trouble as opening a peer-to-peer
connection uses a socket client, which uses a proxy resolver
which may end up using gsettings, whose dconf backend may end
up using the session bus to talk to dconfd...
Also add convenience _with_unix_fd_list variants to GDBusConnection,
GDBusProxy and GDBusMethodInvocation types to easily support this.
Signed-off-by: David Zeuthen <davidz@redhat.com>
This is possible now that we have better support for object path
arrays, see
http://git.gnome.org/browse/glib/commit/?id=19878998bc386db78614f1c92ff8524a81479c7b
Note that this breaks the ABI of generated code but since
gdbus-codegen(1) has never yet been in a stable GLib release, this is
fine.
Signed-off-by: David Zeuthen <davidz@redhat.com>
This commit represents an API break to GAction in the following ways:
- the 'set_state' entry in the GActionInterface vtable has been
renamed to 'change_state'. The number and order of vtable items has
not otherwise changed.
- g_action_set_state() has been renamed to g_action_change_state() to
match the updated vtable entry.
- the "state" property of the GAction interface has been changed to
read-only to reflect the fact that g_action_set_state() no longer
exists.
- GSimpleActionClass has been hidden. GSimpleAction can no longer be
subclassed.
>> Rationale
g_action_set_state() has never been a true setter in the sense that
calling it will update the value of the "state" property. It has always
been closer to "request 'state' to be changed to this value" with
semantics defined by the implementor of the interface. This is why the
equivalent method in GActionGroup had its name changed from 'set' to
'change'. This change makes the two interfaces more consistent and
removes any implication about the effect that calling set_state() should
have on the 'state' property.
>> Impact
This incompatible API break was undertaken only because I strongly
suspect that it will go entirely unnoticed. If the break actually
affects anybody, then we will accommodate them (possibly going as far as
to revert this commit entirely).
The virtual table change only impacts implementors of GAction. I
strongly suspect that this is nobody (except for GSimpleAction).
The hiding of GSimpleActionClass only impacts impacts subclasses of
GSimpleAction. I strongly suspect that none of these exist.
The changing of the property to be read-only only affects people who
were trying to change the state by using GObject properties. I strongly
suspect that this is nobody at all.
The removal of the g_action_set_state() call is the most dangerous, but
I still suspect that it will impact nobody outside of GLib. If anybody
is impacted by this change then, at their request, I will reintroduce
the API as a deprecated alias for g_action_change_state().
... otherwise we might end up using the worker after it has been
freed. Reported by Dan Winship and Colin Walters.
This fix uncovered a bug in the /gdbus/nonce-tcp test case so "fix"
that as well to use a better way of having one thread wait for another
(using quotes for the word "fix" since it's pretty hackish to
busy-wait in one thread to wait for another).
Signed-off-by: David Zeuthen <davidz@redhat.com>
These will validate the resulting line, and throw a conversion error.
In practice these will likely be used by bindings, but it's good
for even C apps too that don't want to explode if that text file
they're reading into Pango actually has invalid UTF-8.
https://bugzilla.gnome.org/show_bug.cgi?id=652758
This avoids the generated types (e.g. ExampleAnimal, ExampleCat,
ExampleObject and ExampleObjectManagerClient) being referenced in the
core gio docs. This was requested by Matthias.
Signed-off-by: David Zeuthen <davidz@redhat.com>
.. and add a C setter to do this. Also make the C getter return a
reference since the property may be set from another thread. Also
change the constructor to _not_ take a GDBusConnection since this is
something you almost always want to do _after_ creating it. The
API/ABI break is fine as there has never been a GLib release with this
type.
https://bugzilla.gnome.org/show_bug.cgi?id=648959
Signed-off-by: David Zeuthen <davidz@redhat.com>
_GNU_SOURCE must be defined before including any other (system)
header, so defining it in glib-unix.h (and hoping no one has included
anything else before that) is wrong. And the "#define _USE_GNU"
workaround for this problem in gnetworkingprivate.h is even wronger
(and still prone to failure anyway due to single-include guards).
Fix this by defining _GNU_SOURCE in config.h when building against
glibc. In theory this is bad because new releases of glibc may include
symbols that conflict with glib symbols, which could then cause
compile failures. However, most people only see new releases of glibc
when they upgrade their distro, at which point they also generally get
new releases of gcc, which have new warnings/errors to clean up
anyway.
https://bugzilla.gnome.org/show_bug.cgi?id=649201
Specific changes
- Use get_type(), not get_gtype() for the GType function
- so we need to use the lower-case name type_ for properties called type
- Don't return a function pointer, just make the function returned
available instead
- Add (type) annotations in constructors so g-ir-scanner detects them as such
- Add (transfer none) annotations to property getters
- Add (out) annotations to D-Bus method call functions
Signed-off-by: David Zeuthen <davidz@redhat.com>
A fairly typical pattern is to have code that does
foo_set_bar (object, "");
if (some_condition)
{
foo_set_bar (object, "yes");
}
where some_condition is often true every time @object is updated.
With this code, bar is essentially always "yes" but because of how
gdbus-codegen works, useless PropertiesChanged events got scheduled
and sent out. With this patch, we avoid that by always keeping the
original value around and comparing it only when we deem it's time to
send out the ::PropertiesChanged signal (typically in an idle but can
be forced by the user via flush()).
Also add a test case for this.
Signed-off-by: David Zeuthen <davidz@redhat.com>
Older versions of libdbus would let you construct an invalid
DBusMessage, but that's a bug, which will be fixed in 1.4.8/1.5.0.
Instead, construct a valid message of the same length, then replace
substrings in the serialized blob with their invalid counterparts.
Bug: https://bugzilla.gnome.org/show_bug.cgi?id=646326
Signed-off-by: David Zeuthen <davidz@redhat.com>
... this was causing a GDBus test-case to fail so now that it is
fixed, also reenable the test case.
https://bugzilla.gnome.org/show_bug.cgi?id=631379
Signed-off-by: David Zeuthen <davidz@redhat.com>
And use this for a) documentation purposes; and b) to preserve C ABI
when an interface is extended. See
https://bugzilla.gnome.org/show_bug.cgi?id=647577#c5
for more details. Also add test cases for this.
Signed-off-by: David Zeuthen <davidz@redhat.com>
Several flaws were pointed out by Shaun McCance. We were
leaking handled arguments, and we were mishandling the last
argument, and we were actually skipping arguments too.
https://bugzilla.gnome.org/show_bug.cgi?id=647031
When using GOption to handle commandlines, we need to disable
the builtin help handling, since it calls exit(). Also mention
this particular pitfall in the docs.
