Skip to content

Shared memory and worker pools

Read the shared-memory guide for negotiation and buffer lifetime, and the pool guide for exclusive leases and worker replacement.

Declarations below are included directly from the public headers.

Shared-memory regions

vgi_rpc/shm.h on GitHub

vgi_rpc/shm.h
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
#ifndef VGI_RPC_SHM_H
#define VGI_RPC_SHM_H
#include "vgi_rpc/batch.h"
#ifdef __cplusplus
extern "C" {
#endif
/* POSIX shared-memory side channel. One lockstep connection per segment.
 * Resolved batches own their buffers and remain valid after reuse or close. */
struct VgiShm;
struct VgiShmStats {
    uint64_t batches_written, batches_read, bytes_written, bytes_read, inline_fallbacks;
};
int VgiShmCreate(int64_t size, struct VgiShm **, struct ArrowError *);
int VgiShmAttach(const char *name, int64_t expected_size, struct VgiShm **, struct ArrowError *);
void VgiShmFree(struct VgiShm *); /* Only the creator unlinks the segment. */
const char *VgiShmName(const struct VgiShm *);
int64_t VgiShmSize(const struct VgiShm *);
void VgiShmGetStats(const struct VgiShm *, struct VgiShmStats *);
/* Threshold defaults to 128 KiB; zero routes every nonempty batch through SHM. */
void VgiShmSetThreshold(struct VgiShm *, int64_t bytes);
#ifdef __cplusplus
}
#endif
#endif

Worker pools

vgi_rpc/pool.h on GitHub

vgi_rpc/pool.h
 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
34
35
36
37
38
39
#ifndef VGI_RPC_POOL_H
#define VGI_RPC_POOL_H
#include "vgi_rpc/client.h"
#ifdef __cplusplus
extern "C" {
#endif
struct VgiWorkerPool;
struct VgiWorkerLease;
struct VgiWorkerPoolOptions {
    /* One pool per subprocess command/configuration. Strings and argv are copied;
     * callback state and external-storage policy must outlive all leases. */
    struct VgiClientOptions client;
    size_t max_workers, max_idle;
    unsigned idle_timeout_ms, acquire_timeout_ms;
};
struct VgiWorkerPoolStats {
    uint64_t spawns, reuses, discards, idle_evictions, timeouts;
    size_t active, idle, waiting;
};
void VgiWorkerPoolOptionsInit(struct VgiWorkerPoolOptions *);
int VgiWorkerPoolNew(const struct VgiWorkerPoolOptions *, struct VgiWorkerPool **,
                     struct ArrowError *);
/* Thread-safe; a lease grants exclusive use of its client. Never free that client.
 * Exhausted pools wait up to acquire_timeout_ms. No RPC is automatically retried. */
int VgiWorkerPoolAcquire(struct VgiWorkerPool *, struct VgiWorkerLease **, struct ArrowError *);
struct VgiClient *VgiWorkerLeaseClient(struct VgiWorkerLease *);
/* Application RPC errors may be reused after framing is drained. Broken peers,
 * abandoned streams, and explicitly discarded leases are terminated and reaped. */
void VgiWorkerLeaseRelease(struct VgiWorkerLease *);
void VgiWorkerLeaseDiscard(struct VgiWorkerLease *);
void VgiWorkerPoolGetStats(struct VgiWorkerPool *, struct VgiWorkerPoolStats *);
void VgiWorkerPoolClose(struct VgiWorkerPool *); /* Wake waiters; reject new borrows. */
/* Stop the idle reaper. Outstanding leases remain valid and keep the pool alive.
 * Do not begin any new pool operation after Free; existing waiters may finish. */
void VgiWorkerPoolFree(struct VgiWorkerPool *);
#ifdef __cplusplus
}
#endif
#endif