Binary interface

The version of Open Graph's binary interface, for bindings in other languages.

#define OG_ABI_VERSION 1

Raised whenever a public function's parameters, a public type's layout or an enumeration's values change in a way a binding written for the previous version would misread. A binding compares it with abi_version() of the library it loaded and refuses a library of another version, rather than passing it arguments it would read wrongly. OG_VERSION_STRING names the library's release; ABI_VERSION only its interface.

Checked

Open Graph extension, no igraph counterpart.

C name

OG_ABI_VERSION

In notebooks

Og.OG_ABI_VERSION

igraph 1.0

None: Open Graph's own.

See also

abi_version, abi_sizeof, version

The version of the binary interface the library was built with.

int og_abi_version(void);

Returns ABI_VERSION as it was when the library was compiled. A host that loads og.dll, libog.dylib or libog.so at run time (OpenBI's notebooks do, from C#) calls it first and stops with a clear message when it differs from the version its own declarations were generated for.

Returns

ABI_VERSION of the library.

Complexity

O(1).

Checked

Open Graph extension (the shared library's binary interface), no igraph counterpart. tests/abi/abi.c checks it against the compiler's own sizeof and offsetof; tools/check_shared.py checks the built library from outside (ctypes), as a host in another language sees it.

C name

og_abi_version

In notebooks

Og.Native.og_abi_version

igraph 1.0

None: Open Graph's own.

See also

ABI_VERSION, abi_sizeof, version

#include "og.h"
#include <stdio.h>

int main(void) {
    /* a host checks the interface before it calls anything else */
    if (og_abi_version() != OG_ABI_VERSION) {
        fprintf(stderr, "built for another Open Graph interface\n");
        return 1;
    }
    printf("og_t is %zu bytes, og_vs_t %zu\n", og_abi_sizeof("og_t"), og_abi_sizeof("og_vs_t"));
    return 0;
}

The size in bytes of a public type, looked up by its C name.

size_t og_abi_sizeof(const char *type);

Every complete public struct, enumeration and plain type the headers declare is in the table (og_t, every vector, matrix and list instance, the selectors og_vs_t and og_es_t, the option structs, og_int_t, og_bool_t ...). A binding allocates a type it does not mirror field by field (og_t, hrg_t, a sparse matrix) as a block of this many bytes, and checks the size of every type it does mirror. The table is written from the headers by tools/gen_abi.py (src/abi/abi_types.inc) and compiled with the compiler's own sizeof, so it is right on every system the library is built for.

Parameters

• type The type's C name, for example "og_vector_int_t".

Returns

The size in bytes; 0 for NULL or a name the library does not know.

Complexity

O(number of public types): a linear search of about 140 names.

Checked

Open Graph extension (the shared library's binary interface), no igraph counterpart. tests/abi/abi.c checks it against the compiler's own sizeof and offsetof; tools/check_shared.py checks the built library from outside (ctypes), as a host in another language sees it.

C name

og_abi_sizeof

In notebooks

Og.Native.og_abi_sizeof

igraph 1.0

None: Open Graph's own.

See also

abi_offsetof, abi_type

The offset in bytes of a field of a public struct.

og_int_t og_abi_offsetof(const char *type, const char *field);

With abi_sizeof, a binding checks its own picture of a struct (the C# mirror of vector_t, og_vs_t, jacobian_options_t ...) field by field against the library it loaded. Fields that are bit-fields have no offset.

Parameters

• type The struct's C name.
• field The field's name, for example "size".

Returns

The offset in bytes, or -1 when the type or the field is unknown (or either argument is NULL).

Complexity

O(number of public fields): a linear search of about 360 entries.

Checked

Open Graph extension (the shared library's binary interface), no igraph counterpart. tests/abi/abi.c checks it against the compiler's own sizeof and offsetof; tools/check_shared.py checks the built library from outside (ctypes), as a host in another language sees it.

C name

og_abi_offsetof

In notebooks

Og.Native.og_abi_offsetof

igraph 1.0

None: Open Graph's own.

See also

abi_sizeof

The names of the public types abi_sizeof knows, one by one.

const char *og_abi_type(og_int_t index);

Indexes 0, 1, 2 ... give the names in alphabetical order; past the last the answer is NULL. A binding walks it to check that every type it relies on is there.

Parameters

• index From 0.

Returns

The name (never to be freed), or NULL for an index out of range.

Complexity

O(1).

Checked

Open Graph extension (the shared library's binary interface), no igraph counterpart. tests/abi/abi.c checks it against the compiler's own sizeof and offsetof; tools/check_shared.py checks the built library from outside (ctypes), as a host in another language sees it.

C name

og_abi_type

In notebooks

Og.Native.og_abi_type

igraph 1.0

None: Open Graph's own.

See also

abi_sizeof

An error handler that keeps the latest error's text on its thread, for hosts that cannot take a callback.

void og_abi_error_handler(
    const char *reason,
    const char *file,
    int line,
    og_error_t og_errno
);

Install it with set_error_handler(abi_error_handler). When a function fails, the handler keeps the first reason the error carried (the calls made by every OG_CHECK on the way up carry none), its code, source file and line, in storage of the calling thread, and then cleans up exactly as error_handler_ignore does, so the error code travels back to the caller. A host clears the record before a call (abi_error_clear) and reads it after a failing one (abi_error_last): that is how OpenBI's notebooks turn an error_t into an exception with Open Graph's own words. A record is replaced only after it is cleared, so the first error of a call is the one reported.

Parameters

• reason The failing function's message (may be empty).
• file The source file.
• line The line.
• og_errno The error code.

Returns

Nothing; the code returns to the caller.

Complexity

O(1).

Checked

Open Graph extension (the shared library's binary interface), no igraph counterpart. tests/abi/abi.c checks it against the compiler's own sizeof and offsetof; tools/check_shared.py checks the built library from outside (ctypes), as a host in another language sees it.

C name

og_abi_error_handler

In notebooks

Og.Native.og_abi_error_handler

igraph 1.0

None: Open Graph's own.

See also

abi_error_last, abi_error_clear, set_error_handler, error_handler_ignore

What abi_error_handler kept on this thread: the reason, code, file and line.

const char *og_abi_error_last(
    og_error_t *og_errno,
    const char **file,
    int *line
);

Returns the reason (an empty string when the failing function gave none) and fills the other arguments that are not NULL. The text belongs to the thread and lives until the next error is recorded there.

Parameters

• og_errno Receives the code; may be NULL.
• file Receives the source file; may be NULL.
• line Receives the line; may be NULL.

Returns

The reason, or NULL when nothing was recorded since abi_error_clear.

Complexity

O(1).

Checked

Open Graph extension (the shared library's binary interface), no igraph counterpart. tests/abi/abi.c checks it against the compiler's own sizeof and offsetof; tools/check_shared.py checks the built library from outside (ctypes), as a host in another language sees it.

C name

og_abi_error_last

In notebooks

Og.Native.og_abi_error_last

igraph 1.0

None: Open Graph's own.

See also

abi_error_handler, abi_error_clear, strerror

Forgets the error kept on this thread.

void og_abi_error_clear(void);

Call it before a call whose failure you want to read: the record is replaced only once it is cleared.

Returns

Nothing.

Complexity

O(1).

Checked

Open Graph extension (the shared library's binary interface), no igraph counterpart. tests/abi/abi.c checks it against the compiler's own sizeof and offsetof; tools/check_shared.py checks the built library from outside (ctypes), as a host in another language sees it.

C name

og_abi_error_clear

In notebooks

Og.Native.og_abi_error_clear

igraph 1.0

None: Open Graph's own.

See also

abi_error_handler, abi_error_last

A warning handler that keeps the warnings on their thread, for hosts that cannot take a callback.

void og_abi_warning_handler(const char *reason, const char *file, int line);

Install it with set_warning_handler(abi_warning_handler). Each warning reported on the calling thread is kept as a line, up to 64 KiB (later ones are dropped). Warnings reported from the worker threads of a parallel kernel stay on those threads.

Parameters

• reason The warning.
• file The source file.
• line The line.

Returns

Nothing.

Complexity

O(1).

Checked

Open Graph extension (the shared library's binary interface), no igraph counterpart. tests/abi/abi.c checks it against the compiler's own sizeof and offsetof; tools/check_shared.py checks the built library from outside (ctypes), as a host in another language sees it.

C name

og_abi_warning_handler

In notebooks

Og.Native.og_abi_warning_handler

igraph 1.0

None: Open Graph's own.

See also

abi_warnings, abi_warnings_clear, set_warning_handler

The warnings kept on this thread, one per line.

const char *og_abi_warnings(void);

What abi_warning_handler kept since abi_warnings_clear; the text belongs to the thread.

Returns

The warnings, each ending in a newline; an empty string when there are none.

Complexity

O(1).

Checked

Open Graph extension (the shared library's binary interface), no igraph counterpart. tests/abi/abi.c checks it against the compiler's own sizeof and offsetof; tools/check_shared.py checks the built library from outside (ctypes), as a host in another language sees it.

C name

og_abi_warnings

In notebooks

Og.Native.og_abi_warnings

igraph 1.0

None: Open Graph's own.

See also

abi_warning_handler, abi_warnings_clear

Forgets the warnings kept on this thread.

void og_abi_warnings_clear(void);

Use it before a call whose warnings you want to read.

Returns

Nothing.

Complexity

O(1).

Checked

Open Graph extension (the shared library's binary interface), no igraph counterpart. tests/abi/abi.c checks it against the compiler's own sizeof and offsetof; tools/check_shared.py checks the built library from outside (ctypes), as a host in another language sees it.

C name

og_abi_warnings_clear

In notebooks

Og.Native.og_abi_warnings_clear

igraph 1.0

None: Open Graph's own.

See also

abi_warnings