If value is floating, sink it. Otherwise, do nothing.
Typically you want to use Variant.refSink in order to
automatically do the correct thing with respect to floating or
non-floating references, but there is one specific scenario where
this function is helpful.
The situation where this function is helpful is when creating an API
that allows the user to provide a callback function that returns a
glib.Variant We certainly want to allow the user the flexibility to
return a non-floating reference from this callback (for the case
where the value that is being returned already exists).
At the same time, the style of the glib.Variant API makes it likely that
for newly-created glib.Variant instances, the user can be saved some
typing if they are allowed to return a glib.Variant with a floating
reference.
Using this function on the return value of the user's callback allows
the user to do whichever is more convenient for them. The caller
will alway receives exactly one full reference to the value: either
the one that was returned in the first place, or a floating reference
that has been converted to a full reference.
This function has an odd interaction when combined with
Variant.refSink running at the same time in another thread on
the same glib.Variant instance. If Variant.refSink runs first then
the result will be that the floating reference is converted to a hard
reference. If Variant.takeRef runs first then the result will
be that the floating reference is converted to a hard reference and
an additional reference on top of that one is added. It is best to
avoid this situation.
If value is floating, sink it. Otherwise, do nothing.
Typically you want to use Variant.refSink in order to automatically do the correct thing with respect to floating or non-floating references, but there is one specific scenario where this function is helpful.
The situation where this function is helpful is when creating an API that allows the user to provide a callback function that returns a glib.Variant We certainly want to allow the user the flexibility to return a non-floating reference from this callback (for the case where the value that is being returned already exists).
At the same time, the style of the glib.Variant API makes it likely that for newly-created glib.Variant instances, the user can be saved some typing if they are allowed to return a glib.Variant with a floating reference.
Using this function on the return value of the user's callback allows the user to do whichever is more convenient for them. The caller will alway receives exactly one full reference to the value: either the one that was returned in the first place, or a floating reference that has been converted to a full reference.
This function has an odd interaction when combined with Variant.refSink running at the same time in another thread on the same glib.Variant instance. If Variant.refSink runs first then the result will be that the floating reference is converted to a hard reference. If Variant.takeRef runs first then the result will be that the floating reference is converted to a hard reference and an additional reference on top of that one is added. It is best to avoid this situation.