Threads

One task of a parallel kernel: runs part task of the kernel's work.

typedef void og_task_fn_t(void *ctx, int task);

An executor calls it once for every task number from 0 to ntasks - 1. The shape is that of the task functions of OpenBI's engine, so OpenBI lends its pool without wrapping each task. Open Graph's tasks never wait for one another and never call the executor again.

Parameters

• ctx The kernel's context, passed through by the executor.
• task The task number, 0 to ntasks - 1.

Returns

Nothing.

Checked

Open Graph extension (CONVENTIONS section 15), no igraph counterpart.

Threads

Part of the executor contract.

C name

og_task_fn_t

In notebooks

Og.TaskFn

igraph 1.0

None: Open Graph's own.

See also

executor_t, set_executor

A host's way of running Open Graph's tasks on its own thread pool.

typedef void og_executor_t(
    void *data,
    int ntasks,
    og_task_fn_t *fn,
    void *ctx
);

An executor runs fn(ctx, t) once for every t from 0 to ntasks - 1, on any threads, in any order, all at once or one after another, and returns when all have returned. Since Open Graph's tasks never wait for each other and never call the executor again (a kernel called inside a task runs on that thread alone), running them one by one on the calling thread is always correct.

For bit-identical results the executor's threads must run with the caller's floating-point environment: Open Graph's tasks set the caller's rounding mode and exception flags on entry and restore the thread's own on exit; flush-to-zero modes outside <fenv.h> are the host's to keep equal. OpenBI's engine lends its pool with a three-line function that hands the tasks to its own parallel loop.

Parameters

• data The pointer given to set_executor.
• ntasks Number of tasks to run.
• fn The task function.
• ctx The kernel's context, passed to every task.

Returns

Nothing; it returns when every task has returned.

Checked

Open Graph extension (CONVENTIONS section 15), no igraph counterpart. Reverse-order and scrambled executors are part of every determinism test.

Threads

Part of the executor contract.

C name

og_executor_t

In notebooks

Og.Executor

igraph 1.0

None: Open Graph's own.

See also

set_executor, task_fn_t

Sets how many threads Open Graph's parallel kernels may use, process-wide.

og_error_t og_set_num_threads(og_int_t n);

1, the default, runs every function on the calling thread alone, exactly as without the thread layer. n > 1 lets a kernel split its work into at most n tasks; 0 means the logical processors of the machine (get_num_procs); values above 1024 are capped at 1024. The kernels that use it: betweenness (all variants), closeness and harmonic centrality, eccentricity, radius, graph center, diameter, average path length, global efficiency, path-length histogram, all-pairs distances (BFS, Dijkstra, Johnson), Jaccard and Dice similarity, triad census, motif counts, Infomap's trials and the Jacobians.

Every parallel kernel gives bit for bit the result of one thread, for every number of threads, every executor and every schedule: work is cut into pieces that do not depend on the thread count, and floating-point sums are added in the one-thread order. Small inputs (under about 200,000 elementary steps) stay on the calling thread. Set the number before the threads that call Open Graph start, as with the error handlers.

Parameters

• n Number of threads: 1 (default), 0 for the logical processors, or more.

Returns

OG_SUCCESS.

Errors

• OG_EINVAL n is negative.

Complexity

O(1). Open Graph's own workers start when a kernel first needs them, then sleep until the process ends.

Checked

Open Graph extension (CONVENTIONS section 15), no igraph counterpart. Every kernel is tested bit for bit at 1, 2, 3, 4, 8 and 16 threads on 200+ random graphs per function, with the own pool and two executors that run tasks in reverse and scrambled order.

Threads

This is the thread layer's main switch.

C name

og_set_num_threads

In notebooks

Og.Native.og_set_num_threads

igraph 1.0

None: Open Graph's own.

See also

get_num_threads, set_executor, get_num_procs

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

int main(void) {
    og_t g;
    og_vector_t bc;
    og_set_num_threads(0);                      /* all logical processors */
    printf("%" OG_PRId " threads\n", og_get_num_threads());
    og_famous(&g, "Zachary");
    og_vector_init(&bc, 0);
    /* same bits as with one thread */
    og_betweenness(&g, NULL, &bc, og_vss_all(), false, false);
    og_vector_destroy(&bc);
    og_destroy(&g);
    og_set_num_threads(1);
    return 0;
}

Returns the number of threads the parallel kernels may use.

og_int_t og_get_num_threads(void);

The value set by set_num_threads after its rules (0 replaced by the processor count, the cap of 1024 applied); 1 by default.

Returns

The current number of threads, at least 1.

Complexity

O(1).

Checked

Open Graph extension (CONVENTIONS section 15), no igraph counterpart.

Threads

Reads the thread layer's setting.

C name

og_get_num_threads

In notebooks

Og.Native.og_get_num_threads

igraph 1.0

None: Open Graph's own.

See also

set_num_threads

Lends a host's thread pool to Open Graph, or restores Open Graph's own threads.

og_error_t og_set_executor(og_executor_t *executor, void *data);

From the next kernel on, parallel work goes to executor (with data as its first argument) instead of Open Graph's own pool; NULL restores the own pool, the default. The setting is process-wide. The own pool uses Win32 threads on Windows, POSIX threads on macOS and other Unix systems, and C11 <threads.h> elsewhere; when another thread is already using it, a kernel runs its tasks itself, one after another.

Parameters

• executor The host's executor, or NULL for Open Graph's own threads.
• data Passed to every call of the executor.

Returns

OG_SUCCESS.

Errors

• OG_FAILURE The thread layer could not be initialised.

Complexity

O(1).

Checked

Open Graph extension (CONVENTIONS section 15), no igraph counterpart.

Threads

Chooses who runs the thread layer's tasks.

C name

og_set_executor

In notebooks

Og.Native.og_set_executor

igraph 1.0

None: Open Graph's own.

See also

executor_t, get_executor, set_num_threads

#include "og.h"

/* A host pool that runs every task (here: one after another on this thread). */
static void host_executor(void *data, int ntasks, og_task_fn_t *fn, void *ctx) {
    int t;
    (void) data;
    for (t = 0; t < ntasks; t++) {
        fn(ctx, t);
    }
}

int main(void) {
    og_set_executor(host_executor, NULL);
    og_set_num_threads(8);           /* kernels split into at most 8 tasks */
    /* ... call Open Graph ... */
    og_set_executor(NULL, NULL);     /* back to Open Graph's own threads */
    og_set_num_threads(1);
    return 0;
}

Returns the installed executor, or NULL for Open Graph's own threads.

og_executor_t *og_get_executor(void **data);

*data, when data is not NULL, receives the pointer given to set_executor (NULL when none is installed).

Parameters

• data Output, may be NULL: the executor's data pointer.

Returns

The installed executor, or NULL.

Complexity

O(1).

Checked

Open Graph extension (CONVENTIONS section 15), no igraph counterpart.

Threads

Reads the thread layer's setting.

C name

og_get_executor

In notebooks

Og.Native.og_get_executor

igraph 1.0

None: Open Graph's own.

See also

set_executor

Returns the number of logical processors of the machine.

og_int_t og_get_num_procs(void);

GetActiveProcessorCount for all processor groups on Windows, sysconf(_SC_NPROCESSORS_ONLN) on POSIX systems, 1 where neither is available. set_num_threads(0) uses this number.

Returns

The logical processor count, at least 1.

Complexity

O(1).

Checked

Open Graph extension (CONVENTIONS section 15), no igraph counterpart.

C name

og_get_num_procs

In notebooks

Og.Native.og_get_num_procs

igraph 1.0

None: Open Graph's own.

See also

set_num_threads