Created attachment 297772 [details] [review]
programming-guidelines: Add a page on asynchronous programming

This covers various techniques for using and defining GAsyncResult-style
asynchronous methods, based around the use of examples.

Review of attachment 297772 [details] [review]:

Skimmed over the code, but you need a review from Ryan.

::: programming-guidelines/C/async-programming.page
@@ +97,3 @@
+      <item>
+        <code mime="text/x-csrc">
+foo_file_load_data_async (FooFile             *self,

Is it worth mentioning the odd API examples (discussed on the mailing list) where the sync variants are foo_sync(), and the async variants are foo()? (probably not)

@@ +177,3 @@
+
+    <p>
+      Which approach is used depends on the class’ design. A class which wraps

Would be nice to use a preposition (rather than the genitive) here (and throughout). "…depends on the design of the class."

(In reply to David King from comment #2)
> Review of attachment 297772 [details] [review] [review]:
> 
> Skimmed over the code, but you need a review from Ryan.
> 
> ::: programming-guidelines/C/async-programming.page
> @@ +97,3 @@
> +      <item>
> +        <code mime="text/x-csrc">
> +foo_file_load_data_async (FooFile             *self,
> 
> Is it worth mentioning the odd API examples (discussed on the mailing list)
> where the sync variants are foo_sync(), and the async variants are foo()?
> (probably not)

I think it probably is worth mentioning briefly.

> @@ +177,3 @@
> +
> +    <p>
> +      Which approach is used depends on the class’ design. A class which
> wraps
> 
> Would be nice to use a preposition (rather than the genitive) here (and
> throughout). "…depends on the design of the class."

Yes, that would be a nice improvement.

I’ll make those changes once review #2 is done by Ryan.

Ryan, would you be able to find some time to look at this please?

Review of attachment 297772 [details] [review]:

::: programming-guidelines/C/main-contexts.page
@@ +464,3 @@
     <p>
+      Always <link xref="async-programming">write things asynchronously</link>
+      internally (using

I have some serious reservations about this style of blanket advice. Writing everything async typically leads to a giant rats nest of callbacks that are really hard to maintain, compared to a nice and clean worker thread. You should inform people about the pros and cons of the various tools at their disposal, and then let them choose the best tool for the job.

Created attachment 313791 [details] [review]
programming-guidelines: Add a page on asynchronous programming

This covers various techniques for using and defining GAsyncResult-style
asynchronous methods, based around the use of examples.

---

Tweaked that paragraph to mention threading, but discourage it.

The programming guidelines are aimed at novice-to-intermediate coders who are getting used to GLib/GNOME, as I understand it. Advanced coders who know the tradeoffs are very welcome to use threads when they are the most appropriate tool. Anyone who is not an advanced coder is pretty much bound to get threading wrong though, so it's not something I particularly want to encourage.

And people don't just get threading wrong: they get it wrong but are convinced they've got it right, because nobody understands race conditions properly.

Ping?

Ping? :-)

Turned into an MR at https://gitlab.gnome.org/GNOME/gnome-devel-docs/merge_requests/13.