Description

As a general rule Cogl shields non-recoverable errors from developers, such as most heap allocation failures (unless for exceptionally large resources which we might reasonably expect to fail) and this reduces the burden on developers.

There are some Cogl apis though that can fail for exceptional reasons that can also potentially be recovered from at runtime and for these apis we use a standard convention for reporting runtime recoverable errors.

As an example if we look at the cogl_context_new() api which takes an error argument:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

CoglContext *
  cogl_context_new (CoglDisplay *display, CoglError **error);

A caller interested in catching any runtime error when creating a new CoglContext would pass the address of a CoglError pointer that has first been initialized to NULL as follows:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

CoglError *error = NULL;
  CoglContext *context;

  context = cogl_context_new (NULL, &error);

The return status should usually be enough to determine if there was an error set (in this example we can check if context == NULL) but if it's not possible to tell from the function's return status you can instead look directly at the error pointer which you initialized to NULL. In this example we now check the error, report any error to the user, free the error and then simply abort without attempting to recover.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

if (context == NULL)
    {
      fprintf (stderr, "Failed to create a Cogl context: %s\n",
               error->message);
      cogl_error_free (error);
      abort ();
    }

All Cogl APIs that accept an error argument can also be passed a NULL pointer. In this case if an exceptional error condition is hit then Cogl will simply log the error message and abort the application. This can be compared to language execeptions where the developer has not attempted to catch the exception. This means the above example is essentially redundant because it's what Cogl would have done automatically and so, similarly, if your application has no way to recover from a particular error you might just as well pass a NULL CoglError pointer to save a bit of typing.

Details

#define CoglError GError

CoglBool            cogl_error_matches                  (CoglError *error,
                                                         uint32_t domain,
                                                         int code);

void                cogl_error_free                     (CoglError *error);

CoglError *         cogl_error_copy                     (CoglError *error);

#define COGL_GLIB_ERROR(COGL_ERROR) ((CoglError *)COGL_ERROR)