/ 
Data-Graph-Shared-0.02
/ Data::Graph::Shared

NAME

Data::Graph::Shared - Shared-memory directed weighted graph for Linux

SYNOPSIS

use Data::Graph::Shared;

my $g = Data::Graph::Shared->new(undef, 100, 500);  # 100 nodes, 500 edges
my $a = $g->add_node(10);    # returns node index
my $b = $g->add_node(20);
my $c = $g->add_node(30);

$g->add_edge($a, $b, 5);     # a→b weight 5
$g->add_edge($a, $c, 3);     # a→c weight 3
$g->add_edge($b, $c, 1);     # b→c weight 1

my @nbrs = $g->neighbors($a);  # ([1,5], [2,3]) — [dst, weight] pairs
say $g->degree($a);            # 2
say $g->node_data($a);         # 10

$g->remove_node($b);          # removes node and outgoing edges

DESCRIPTION

Directed weighted graph in shared memory. Nodes allocated from a bitmap pool, edges stored as adjacency lists in a separate edge pool. Mutex-protected mutations with PID-based stale recovery.

Note: remove_node removes the node and its outgoing edges only. Incoming edges from other nodes are NOT automatically removed (this is an O(1) design choice) — their dst is left dangling until the slot's bit is reused. Use remove_node_full when this matters; it additionally splices incoming edges in O(N+E).

Linux-only. Requires 64-bit Perl.

METHODS

Constructors

my $g = Data::Graph::Shared->new($path, $max_nodes, $max_edges);  # file-backed
my $g = Data::Graph::Shared->new(undef, $max_nodes, $max_edges);  # anonymous
my $g = Data::Graph::Shared->new_memfd($name, $max_nodes, $max_edges);
my $g = Data::Graph::Shared->new_from_fd($fd);                    # reopen memfd

Operations

my $id = $g->add_node($data);            # returns node index or undef
$g->add_edge($src, $dst);                # weight defaults to 1
$g->add_edge($src, $dst, $weight);
$g->remove_node($id);                    # O(1) — outgoing edges only
$g->remove_node_full($id);               # O(N+E) — also splices incoming
$g->has_node($id);
$g->node_data($id);
$g->set_node_data($id, $data);
my @pairs = $g->neighbors($id);          # list of [$dst, $weight]
$g->each_neighbor($id, sub { my ($dst, $w) = @_ });
$g->degree($id);
my @ids = $g->nodes;                     # all node indices
$g->node_count;  $g->edge_count;
$g->max_nodes;   $g->max_edges;

Lifecycle

$g->path;              # backing file path, or undef for anon/memfd
$g->memfd;             # memfd fd (-1 for file-backed/anon)
$g->stats;             # diagnostic hashref
$g->sync;              # msync mmap to backing store
$g->unlink;            # remove backing file
Class->unlink($path);  # class-method form

Event Loop Integration

my $fd = $g->eventfd;         # lazy-create eventfd, returns fd
$g->eventfd_set($fd);         # attach an external eventfd
my $fd = $g->fileno;          # current eventfd fd, or -1
$g->notify;                   # write 1 to eventfd (caller signals update)
my $n = $g->eventfd_consume;  # read+reset eventfd counter

BENCHMARKS

Single-process (10K ops, x86_64 Linux, Perl 5.40):

add_node            3.9M/s
add_edge (random)   2.3M/s
has_node           13.3M/s
node_data           5.5M/s
neighbors           2.6M/s
degree              5.6M/s

STATS

stats() returns: node_count, edge_count, max_nodes, max_edges, ops, mmap_size.

SECURITY

The mmap region is writable by all processes that open it. Do not share backing files with untrusted processes.

SEE ALSO

Data::Heap::Shared - priority queue (for Dijkstra, Prim, etc.)

Data::Pool::Shared - fixed-size object pool

Data::HashMap::Shared - concurrent hash table

Data::Buffer::Shared - typed shared array

Data::Queue::Shared - FIFO queue

Data::Stack::Shared - LIFO stack

Data::Deque::Shared - double-ended queue

Data::Log::Shared - append-only log

Data::Sync::Shared - synchronization primitives

Data::PubSub::Shared - publish-subscribe ring

Data::ReqRep::Shared - request-reply

Data::BitSet::Shared - shared bitset (lock-free per-bit ops)

Data::RingBuffer::Shared - fixed-size overwriting ring buffer

AUTHOR

vividsnow

LICENSE

This is free software; you can redistribute it and/or modify it under the same terms as Perl itself.