lib: strictly type function return status enumerations

lib: strictly type function return status enumerations

Rigour strikes again.

This patch makes each function (or group of related functions) of the
library which returns a status enumeration return its own,
function-specific status enumeration.

For example, where bt_graph_run() used to return the generic
`bt_graph_status` type, it now returns `bt_graph_run_status`.

The benefits are:

* Each function defines its own set of available status codes. With
  appropriate compiler warnings, you can catch comparisons between a
  returned status and an incompatible enumerator, and assignments of
  incompatible enumerators. For example, with clang 8:

      file.c:13:13: warning: implicit conversion from enumeration type
      'enum bt_component_class_init_method_status'
      to different enumeration type
      'enum bt_component_class_port_connected_method_status'
      [-Wenum-conversion]
        bt_component_class_port_connected_method_status status =
          BT_COMPONENT_CLASS_INIT_METHOD_STATUS_ERROR;

  This was not possible before because all the status-returning
  functions of a given header could possibly return any value defined by
  the header-wide status enumeration.

* A function's possible return values are self-documented: there's no
  need to document that a given function can only return some subset of
  the header-wide status enumerators.

* In future minor releases of Babeltrace 2, we can add new status codes
  for a specific function.

* Some smart IDEs will list the possible enumerators when checking the
  return value of a function or when returning a value from a function.

To uniformize the status enumerator integer values, the new
`<babeltrace2/func-status.h>` public header contains definitions for all
the possible status codes. They are definitions instead of enumerators
because they are not meant to be used directly by user code.

To make sure a user does not write:

    #include <babeltrace2/func-status.h>

to use the `__BT_FUNC_STATUS_*` definitions directly (which would
inhibit the precious type checking that this patch is all about), the
compiler will show the error:

> Do NOT include <babeltrace2/func-status.h> in user code.

unless you define `__BT_FUNC_STATUS_ENABLE` before including the header.

Each public header which needs `__BT_FUNC_STATUS_*` definitions to
define its own status enumerations does:

    /* For __BT_FUNC_STATUS_* */
    #define __BT_FUNC_STATUS_ENABLE
    #include <babeltrace2/func-status.h>
    #undef __BT_FUNC_STATUS_ENABLE

at the beginning of the file, and:

    #include <babeltrace2/undef-func-status.h>

at the end of the file. The `<babeltrace2/undef-func-status.h>` header
cancels all the existing `__BT_FUNC_STATUS_*` definitions so that they
are not available to user code.

Within the library, `"lib/func-status.h"` uses the definitions of
`<babeltrace2/func-status.h>` to define its own, similar definitions,
but without the `__` prefix for improved internal code readability.
Internal library code does not need to "undefine" those definitions.

As this system guarantees that any public status enumerator is an alias
of one of the `__BT_FUNC_STATUS_*` definitions, the library code never
uses the function-specific status enumerators directly: it always uses
one of the `BT_FUNC_STATUS_*` definitions found in
`"lib/func-status.h"`. This made it easier to adapt existing code. This
also allows to pass such status codes easily between internal and public
functions because they are `int` values until they finally reach public
enumeration types where they are implicitly casted.

When an internal (hidden, static) function returns a status code, it now
returns `int`, using one of the `BT_FUNC_STATUS_*` values, where this
could be used by at least two functions returning different public
status enumerations.

In internal headers, all the bt_*_status_string() are removed in favor
of bt_common_func_status_string() which returns only the suffix string
(e.g., `OK`, `ERROR`, `OVERFLOW`). This function is typically used when
logging.

The `*_NOMEM` enumerators are renamed to `*_MEMORY_ERROR` to make this
clear and remove this abbreviation which was the only one amongst other
public status enumerators.

Because the Python bindings are within the Babeltrace project, they use
the `__BT_FUNC_STATUS_*` definitions internally. Those values will not
change in the future anyway. All the _handle_*status() and
bt2.utils._handle_ret() functions are removed in favor of
bt2.utils._handle_func_status() which can handle all the possible status
codes and raise a corresponding exception, possibly with a given
message.

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Change-Id: I3966ac0e691219102897920617711c518c34fbdf