This repository was archived by the owner on Sep 9, 2025. It is now read-only.
-
Notifications
You must be signed in to change notification settings - Fork 162
Expand file tree
/
Copy pathstack-graphs.h
More file actions
852 lines (750 loc) · 43.3 KB
/
stack-graphs.h
File metadata and controls
852 lines (750 loc) · 43.3 KB
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
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
#ifndef STACK_GRAPHS_H_
#define STACK_GRAPHS_H_
/* Warning, this file is autogenerated by cbindgen. Don't modify this manually. */
#include <stdarg.h>
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#include <stdlib.h>
// The null value for all of our handles.
#define SG_NULL_HANDLE 0
// The handle of an empty list.
#define SG_LIST_EMPTY_HANDLE 4294967295
// The local_id of the singleton root node.
#define SG_ROOT_NODE_ID 1
// The local_id of the singleton "jump to scope" node.
#define SG_JUMP_TO_NODE_ID 2
// Describes in which direction the content of a deque is stored in memory.
enum sg_deque_direction {
SG_DEQUE_FORWARDS,
SG_DEQUE_BACKWARDS,
};
// The different kinds of node that can appear in a stack graph.
enum sg_node_kind {
// Removes everything from the current scope stack.
SG_NODE_KIND_DROP_SCOPES,
// The singleton "jump to" node, which allows a name binding path to jump back to another part
// of the graph.
SG_NODE_KIND_JUMP_TO,
// Pops a scoped symbol from the symbol stack. If the top of the symbol stack doesn't match
// the requested symbol, or if the top of the symbol stack doesn't have an attached scope
// list, then the path is not allowed to enter this node.
SG_NODE_KIND_POP_SCOPED_SYMBOL,
// Pops a symbol from the symbol stack. If the top of the symbol stack doesn't match the
// requested symbol, then the path is not allowed to enter this node.
SG_NODE_KIND_POP_SYMBOL,
// Pushes a scoped symbol onto the symbol stack.
SG_NODE_KIND_PUSH_SCOPED_SYMBOL,
// Pushes a symbol onto the symbol stack.
SG_NODE_KIND_PUSH_SYMBOL,
// The singleton root node, which allows a name binding path to cross between files.
SG_NODE_KIND_ROOT,
// A node that adds structure to the graph. If the node is exported, it can be
// referred to on the scope stack, which allows "jump to" nodes in any other
// part of the graph can jump back here.
SG_NODE_KIND_SCOPE,
};
// Describes the result of a computation
enum sg_result {
SG_RESULT_SUCCESS,
SG_RESULT_CANCELLED,
};
// Manages the state of a collection of partial paths to be used in the path-stitching algorithm.
struct sg_partial_path_arena;
// Contains a "database" of partial paths.
//
// This type is meant to be a lazily loaded "view" into a proper storage layer. During the
// path-stitching algorithm, we repeatedly try to extend a currently incomplete path with any
// partial paths that are compatible with it. For large codebases, or projects with a large
// number of dependencies, it can be prohibitive to load in _all_ of the partial paths up-front.
// We've written the path-stitching algorithm so that you have a chance to only load in the
// partial paths that are actually needed, placing them into a sg_partial_path_database instance
// as they're needed.
struct sg_partial_path_database;
// A list of paths found by the path-finding algorithm.
struct sg_partial_path_list;
// Contains all of the nodes and edges that make up a stack graph.
struct sg_stack_graph;
// A name that we are trying to resolve using stack graphs.
//
// This typically represents a portion of an identifier as it appears in the source language. It
// can also represent some other "operation" that can occur in source code, and which needs to be
// modeled in a stack graph — for instance, many languages will use a "fake" symbol named `.` to
// represent member access.
struct sg_symbol {
const char *symbol;
size_t symbol_len;
};
// An array of all of the symbols in a stack graph. Symbol handles are indices into this array.
// There will never be a valid symbol at index 0; a handle with the value 0 represents a missing
// symbol.
struct sg_symbols {
const struct sg_symbol *symbols;
size_t count;
};
// A handle to a symbol in a stack graph. A zero handle represents a missing symbol.
//
// We deduplicate symbols in a stack graph — that is, we ensure that there are never multiple
// `struct sg_symbol` instances with the same content. That means that you can compare symbol
// handles using simple equality, without having to dereference them.
typedef uint32_t sg_symbol_handle;
// Arbitrary string content associated with some part of a stack graph.
struct sg_string {
const char *content;
size_t length;
};
// An array of all of the interned strings in a stack graph. String handles are indices into this
// array. There will never be a valid string at index 0; a handle with the value 0 represents a
// missing string.
struct sg_strings {
const struct sg_string *strings;
size_t count;
};
// A handle to an interned string in a stack graph. A zero handle represents a missing string.
//
// We deduplicate strings in a stack graph — that is, we ensure that there are never multiple
// `struct sg_string` instances with the same content. That means that you can compare string
// handles using simple equality, without having to dereference them.
typedef uint32_t sg_string_handle;
// A source file that we have extracted stack graph data from.
//
// It's up to you to choose what names to use for your files, but they must be unique within a
// stack graph. If you are analyzing files from the local filesystem, the file's path is a good
// choice. If your files belong to packages or repositories, they should include the package or
// repository IDs to make sure that files in different packages or repositories don't clash with
// each other.
struct sg_file {
const char *name;
size_t name_len;
};
// An array of all of the files in a stack graph. File handles are indices into this array.
// There will never be a valid file at index 0; a handle with the value 0 represents a missing
// file.
struct sg_files {
const struct sg_file *files;
size_t count;
};
// A handle to a file in a stack graph. A zero handle represents a missing file.
//
// We deduplicate files in a stack graph — that is, we ensure that there are never multiple
// `struct sg_file` instances with the same filename. That means that you can compare file
// handles using simple equality, without having to dereference them.
typedef uint32_t sg_file_handle;
// Uniquely identifies a node in a stack graph.
//
// Each node (except for the _root node_ and _jump to scope_ node) lives in a file, and has a
// _local ID_ that must be unique within its file.
struct sg_node_id {
sg_file_handle file;
uint32_t local_id;
};
// A node in a stack graph.
struct sg_node {
enum sg_node_kind kind;
struct sg_node_id id;
// The symbol associated with this node. For push nodes, this is the symbol that will be
// pushed onto the symbol stack. For pop nodes, this is the symbol that we expect to pop off
// the symbol stack. For all other node types, this will be null.
sg_symbol_handle symbol;
// The scope associated with this node. For push scope nodes, this is the scope that will be
// attached to the symbol before it's pushed onto the symbol stack. For all other node types,
// this will be null.
struct sg_node_id scope;
// Whether this node is an endpoint. For push nodes, this indicates that the node represents
// a reference in the source. For pop nodes, this indicates that the node represents a
// definition in the source. For scopes, this indicates that the scope is exported. For all
// other node types, this field will be unused.
bool is_endpoint;
};
// An array of all of the nodes in a stack graph. Node handles are indices into this array.
// There will never be a valid node at index 0; a handle with the value 0 represents a missing
// node.
struct sg_nodes {
const struct sg_node *nodes;
size_t count;
};
// A handle to a node in a stack graph. A zero handle represents a missing node.
typedef uint32_t sg_node_handle;
// Connects two nodes in a stack graph.
//
// These edges provide the basic graph connectivity that allow us to search for name binding paths
// in a stack graph. (Though not all sequence of edges is a well-formed name binding: the nodes
// that you encounter along the path must also satisfy all of the rules for maintaining correct
// symbol and scope stacks.)
struct sg_edge {
sg_node_handle source;
sg_node_handle sink;
int32_t precedence;
};
// The offset of a character within a string (typically a line of source code), using several
// different units
//
// All offsets are 0-indexed.
struct sg_offset {
// The number of UTF-8-encoded bytes appearing before this character in the string
size_t utf8_offset;
// The number of UTF-16 code units appearing before this character in the string
size_t utf16_offset;
// The number of graphemes appearing before this character in the string
size_t grapheme_offset;
};
// A half-open range identifying a range of characters in a string.
struct sg_utf8_bounds {
// The UTF-8 byte index of the first character in the range.
size_t start;
// The UTF-8 byte index of the first character _after_ the range.
size_t end;
};
// All of the position information that we have about a character in a source file
struct sg_position {
// The 0-indexed line number containing the character
size_t line;
// The offset of the character within its containing line, expressed as both a UTF-8 byte
// index and a UTF-16 code point index
struct sg_offset column;
// The UTF-8 byte indexes (within the file) of the start and end of the line containing the
// character
struct sg_utf8_bounds containing_line;
// The UTF-8 byte indexes (within the file) of the start and end of the line containing the
// character, with any leading and trailing whitespace removed
struct sg_utf8_bounds trimmed_line;
};
// All of the position information that we have about a range of content in a source file
struct sg_span {
struct sg_position start;
struct sg_position end;
};
// Contains information about a range of code in a source code file.
struct sg_source_info {
// The location in its containing file of the source code that this node represents.
struct sg_span span;
// The kind of syntax entity this node represents (e.g. `function`, `class`, `method`, etc.).
sg_string_handle syntax_type;
// The full content of the line containing this node in its source file.
sg_string_handle containing_line;
// The location in its containing file of the source code that this node's definiens represents.
// This is used for things like the bodies of functions, rather than the RHSes of equations.
// If you need one of these to make the type checker happy, but you don't have one, just use
// sg_span::default(), as this will correspond to the all-0s spans which mean "no definiens".
struct sg_span definiens_span;
// The fully qualified name is a representation of the symbol that captures its name and its
// embedded context (e.g. `foo.bar` for the symbol `bar` defined in the module `foo`).
sg_string_handle fully_qualified_name;
};
// An array of all of the source information in a stack graph. Source information is associated
// with nodes, so node handles are indices into this array. It is _not_ guaranteed that there
// will an entry in this array for every node handle; if you have a node handle whose value is
// larger than `count`, then use a 0-valued `sg_source_info` if you need source information for
// that node.
//
// There will never be a valid entry at index 0; a handle with the value 0 represents a missing
// node.
struct sg_source_infos {
const struct sg_source_info *infos;
size_t count;
};
// A tuple of a node handle and source information for that node. Used with the
// `sg_add_source_info` function to add source information to a stack graph.
struct sg_node_source_info {
sg_node_handle node;
struct sg_source_info source_info;
};
// A handle to an element of a partial scope stack. A zero handle represents a missing partial
// scope stack. A UINT32_MAX handle represents an empty partial scope stack.
typedef uint32_t sg_partial_scope_stack_cell_handle;
// Represents an unknown list of exported scopes.
typedef uint32_t sg_scope_stack_variable;
// A pattern that might match against a scope stack. Consists of a (possibly empty) list of
// exported scopes, along with an optional scope stack variable.
struct sg_partial_scope_stack {
// The handle of the first element in the partial scope stack, or SG_LIST_EMPTY_HANDLE if the
// list is empty, or 0 if the list is null.
sg_partial_scope_stack_cell_handle cells;
enum sg_deque_direction direction;
uint32_t length;
// The scope stack variable representing the unknown content of a partial scope stack, or 0 if
// the variable is missing. (If so, this partial scope stack can only match a scope stack
// with exactly the list of scopes in `cells`, instead of any scope stack with those scopes as
// a prefix.)
sg_scope_stack_variable variable;
};
// A symbol with an unknown, but possibly empty, list of exported scopes attached to it.
struct sg_partial_scoped_symbol {
sg_symbol_handle symbol;
struct sg_partial_scope_stack scopes;
};
// A handle to an element of a partial symbol stack. A zero handle represents a missing partial
// symbol stack. A UINT32_MAX handle represents an empty partial symbol stack.
typedef uint32_t sg_partial_symbol_stack_cell_handle;
// An element of a partial symbol stack.
struct sg_partial_symbol_stack_cell {
// The partial scoped symbol at this position in the partial symbol stack.
struct sg_partial_scoped_symbol head;
// The handle of the next element in the partial symbol stack, or SG_LIST_EMPTY_HANDLE if this
// is the last element.
sg_partial_symbol_stack_cell_handle tail;
// The handle of the reversal of this partial scope stack.
sg_partial_symbol_stack_cell_handle reversed;
};
// The array of all of the partial symbol stack content in a partial path arena.
struct sg_partial_symbol_stack_cells {
const struct sg_partial_symbol_stack_cell *cells;
size_t count;
};
// Represents an unknown list of scoped symbols.
typedef uint32_t sg_symbol_stack_variable;
// A pattern that might match against a symbol stack. Consists of a (possibly empty) list of
// partial scoped symbols.
//
// (Note that unlike partial scope stacks, we don't store any "symbol stack variable" here. We
// could! But with our current path-finding rules, every partial path will always have exactly
// one symbol stack variable, which will appear at the end of its precondition and postcondition.
// So for simplicity we just leave it out. At some point in the future we might add it in so that
// the symbol and scope stack formalisms and implementations are more obviously symmetric.)
struct sg_partial_symbol_stack {
// The handle of the first element in the partial symbol stack, or SG_LIST_EMPTY_HANDLE if the
// list is empty, or 0 if the list is null.
sg_partial_symbol_stack_cell_handle cells;
enum sg_deque_direction direction;
uint32_t length;
// The symbol stack variable representing the unknown content of a partial symbol stack, or 0
// if the variable is missing. (If so, this partial symbol stack can only match a symbol
// stack with exactly the list of symbols in `cells`, instead of any symbol stack with those
// symbols as a prefix.)
sg_symbol_stack_variable variable;
};
// An element of a partial scope stack.
struct sg_partial_scope_stack_cell {
// The exported scope at this position in the partial scope stack.
sg_node_handle head;
// The handle of the next element in the partial scope stack, or SG_LIST_EMPTY_HANDLE if this
// is the last element.
sg_partial_scope_stack_cell_handle tail;
// The handle of the reversal of this partial scope stack.
sg_partial_scope_stack_cell_handle reversed;
};
// The array of all of the partial scope stack content in a partial path arena.
struct sg_partial_scope_stack_cells {
const struct sg_partial_scope_stack_cell *cells;
size_t count;
};
// Details about one of the edges in a partial path
struct sg_partial_path_edge {
struct sg_node_id source_node_id;
int32_t precedence;
};
// A handle to an element of a partial path edge list. A zero handle represents a missing partial
// path edge list. A UINT32_MAX handle represents an empty partial path edge list.
typedef uint32_t sg_partial_path_edge_list_cell_handle;
// An element of a partial path edge list.
struct sg_partial_path_edge_list_cell {
// The partial path edge at this position in the partial path edge list.
struct sg_partial_path_edge head;
// The handle of the next element in the partial path edge list, or SG_LIST_EMPTY_HANDLE if
// this is the last element.
sg_partial_path_edge_list_cell_handle tail;
// The handle of the reversal of this list.
sg_partial_path_edge_list_cell_handle reversed;
};
// The array of all of the partial path edge list content in a partial path arena.
struct sg_partial_path_edge_list_cells {
const struct sg_partial_path_edge_list_cell *cells;
size_t count;
};
// The edges in a path keep track of precedence information so that we can correctly handle
// shadowed definitions.
struct sg_partial_path_edge_list {
// The handle of the first element in the edge list, or SG_LIST_EMPTY_HANDLE if the list is
// empty, or 0 if the list is null.
sg_partial_path_edge_list_cell_handle cells;
enum sg_deque_direction direction;
uint32_t length;
};
// A portion of a name-binding path.
//
// Partial paths can be computed _incrementally_, in which case all of the edges in the partial
// path belong to a single file. At query time, we can efficiently concatenate partial paths to
// yield a name-binding path.
//
// Paths describe the contents of the symbol stack and scope stack at the end of the path.
// Partial paths, on the other hand, have _preconditions_ and _postconditions_ for each stack.
// The precondition describes what the stack must look like for us to be able to concatenate this
// partial path onto the end of a path. The postcondition describes what the resulting stack
// looks like after doing so.
//
// The preconditions can contain _scope stack variables_, which describe parts of the scope stack
// (or parts of a scope symbol's attached scope list) whose contents we don't care about. The
// postconditions can _also_ refer to those variables, and describe how those variable parts of
// the input scope stacks are carried through unmodified into the resulting scope stack.
struct sg_partial_path {
sg_node_handle start_node;
sg_node_handle end_node;
struct sg_partial_symbol_stack symbol_stack_precondition;
struct sg_partial_symbol_stack symbol_stack_postcondition;
struct sg_partial_scope_stack scope_stack_precondition;
struct sg_partial_scope_stack scope_stack_postcondition;
struct sg_partial_path_edge_list edges;
};
// An array of all of the partial paths in a partial path database. Partial path handles are
// indices into this array. There will never be a valid partial path at index 0; a handle with
// the value 0 represents a missing partial path.
struct sg_partial_paths {
const struct sg_partial_path *paths;
size_t count;
};
// A handle to a partial path in a partial path database. A zero handle represents a missing
// partial path.
typedef uint32_t sg_partial_path_handle;
// Encodes a set of node handles.
//
// The elements are encoded in a bit set. Use the traditional mask and shift pattern to determine
// if a particular handle is in the set:
//
// ``` c
// size_t element_index = handle / 32;
// size_t bit_index = handle % 32;
// size_t bit_mask = 1 << bit_index;
// bool bit_is_set =
// element_index < set.length &&
// (set.elements[element_index] & bit_mask) != 0;
// ```
struct sg_node_handle_set {
const uint32_t *elements;
// Note that this is the number of uint32_t's in `elements`, NOT the number of bits in the set.
size_t length;
};
// Implements a phased forward partial path stitching algorithm.
//
// Our overall goal is to start with a set of _seed_ partial paths, and to repeatedly extend each
// partial path by concatenating another, compatible partial path onto the end of it. (If there
// are multiple compatible partial paths, we concatenate each of them separately, resulting in
// more than one extension for the current path.)
//
// We perform this processing in _phases_. At the start of each phase, we have a _current set_ of
// partial paths that need to be processed. As we extend those partial paths, we add the
// extensions to the set of partial paths to process in the _next_ phase. Phases are processed
// one at a time, each time you invoke `sg_forward_partial_path_stitcher_process_next_phase`.
//
// After each phase has completed, the `previous_phase_paths` and `previous_phase_paths_length`
// fields give you all of the partial paths that were discovered during that phase. That gives
// you a chance to add to the `sg_partial_path_database` all of the other partial paths that we
// might need to extend those partial paths with before invoking the next phase.
struct sg_forward_partial_path_stitcher {
// The new candidate partial paths that were discovered in the most recent phase.
const struct sg_partial_path *previous_phase_partial_paths;
// The number of new candidate partial paths that were discovered in the most recent phase.
// If this is 0, then the partial path stitching algorithm is complete.
size_t previous_phase_partial_paths_length;
// Whether the stitching algorithm is complete. You should keep calling
// `sg_forward_partial_path_stitcher_process_next_phase` until this field is true.
bool is_complete;
};
// The handle of the singleton root node.
#define SG_ROOT_NODE_HANDLE 1
// The handle of the singleton "jump to scope" node.
#define SG_JUMP_TO_NODE_HANDLE 2
#ifdef __cplusplus
extern "C" {
#endif // __cplusplus
// Creates a new, initially empty stack graph.
struct sg_stack_graph *sg_stack_graph_new(void);
// Frees a stack graph, and all of its contents.
void sg_stack_graph_free(struct sg_stack_graph *graph);
// Creates a new, initially empty partial path arena.
struct sg_partial_path_arena *sg_partial_path_arena_new(void);
// Frees a path arena, and all of its contents.
void sg_partial_path_arena_free(struct sg_partial_path_arena *partials);
// Creates a new, initially empty partial path database.
struct sg_partial_path_database *sg_partial_path_database_new(void);
// Frees a partial path database, and all of its contents.
void sg_partial_path_database_free(struct sg_partial_path_database *db);
// Ensures all partial paths in the database are availabe in both forwards and backwards orientation.
void sg_partial_path_database_ensure_both_directions(struct sg_partial_path_database *db,
struct sg_partial_path_arena *partials);
// Ensures all partial paths in the database are in forwards orientation.
void sg_partial_path_database_ensure_forwards(struct sg_partial_path_database *db,
struct sg_partial_path_arena *partials);
// Returns a reference to the array of symbol data in this stack graph. The resulting array
// pointer is only valid until the next call to any function that mutates the stack graph.
struct sg_symbols sg_stack_graph_symbols(const struct sg_stack_graph *graph);
// Adds new symbols to the stack graph. You provide all of the symbol content concatenated
// together into a single string, and an array of the lengths of each symbol. You also provide an
// output array, which must have the same size as `lengths`. We will place each symbol's handle
// in the output array.
//
// We ensure that there is only ever one copy of a particular symbol stored in the graph — we
// guarantee that identical symbols will have the same handles, meaning that you can compare the
// handles using simple integer equality.
//
// We copy the symbol data into the stack graph. The symbol content you pass in does not need to
// outlive the call to this function.
//
// Each symbol must be a valid UTF-8 string. If any symbol isn't valid UTF-8, it won't be added
// to the stack graph, and the corresponding entry in the output array will be the null handle.
void sg_stack_graph_add_symbols(struct sg_stack_graph *graph,
size_t count,
const char *symbols,
const size_t *lengths,
sg_symbol_handle *handles_out);
// Returns a reference to the array of string data in this stack graph. The resulting array
// pointer is only valid until the next call to any function that mutates the stack graph.
struct sg_strings sg_stack_graph_strings(const struct sg_stack_graph *graph);
// Adds new strings to the stack graph. You provide all of the string content concatenated
// together into a single string, and an array of the lengths of each string. You also provide an
// output array, which must have the same size as `lengths`. We will place each string's handle
// in the output array.
//
// We ensure that there is only ever one copy of a particular string stored in the graph — we
// guarantee that identical strings will have the same handles, meaning that you can compare the
// handles using simple integer equality.
//
// We copy the string data into the stack graph. The string content you pass in does not need to
// outlive the call to this function.
//
// Each string must be a valid UTF-8 string. If any string isn't valid UTF-8, it won't be added
// to the stack graph, and the corresponding entry in the output array will be the null handle.
void sg_stack_graph_add_strings(struct sg_stack_graph *graph,
size_t count,
const char *strings,
const size_t *lengths,
sg_string_handle *handles_out);
// Returns a reference to the array of file data in this stack graph. The resulting array pointer
// is only valid until the next call to any function that mutates the stack graph.
struct sg_files sg_stack_graph_files(const struct sg_stack_graph *graph);
// Adds new files to the stack graph. You provide all of the file content concatenated together
// into a single string, and an array of the lengths of each file. You also provide an output
// array, which must have the same size as `lengths`. We will place each file's handle in the
// output array.
//
// There can only ever be one file with a particular name in the graph. If you try to add a file
// with a name that already exists, you'll get the same handle as a result.
//
// We copy the filenames into the stack graph. The filenames you pass in do not need to outlive
// the call to this function.
//
// Each filename must be a valid UTF-8 string. If any filename isn't valid UTF-8, it won't be
// added to the stack graph, and the corresponding entry in the output array will be the null
// handle.
void sg_stack_graph_add_files(struct sg_stack_graph *graph,
size_t count,
const char *files,
const size_t *lengths,
sg_file_handle *handles_out);
// Returns a reference to the array of nodes in this stack graph. The resulting array pointer is
// only valid until the next call to any function that mutates the stack graph.
struct sg_nodes sg_stack_graph_nodes(const struct sg_stack_graph *graph);
// Adds new nodes to the stack graph. You provide an array of `struct sg_node` instances. You
// also provide an output array, which must have the same length as `nodes`, in which we will
// place each node's handle in the stack graph.
//
// We copy the node content into the stack graph. The array you pass in does not need to outlive
// the call to this function.
//
// You cannot add new instances of the root node or "jump to scope" node, since those are
// singletons and already exist in the stack graph.
//
// If you try to add a new node that has the same ID as an existing node in the stack graph, the
// new node will be ignored, and the corresponding entry in the `handles_out` array will contain
// the handle of the _existing_ node with that ID.
//
// If any node that you pass in is invalid, it will not be added to the graph, and the
// corresponding entry in the `handles_out` array will be null.
void sg_stack_graph_get_or_create_nodes(struct sg_stack_graph *graph,
size_t count,
const struct sg_node *nodes,
sg_node_handle *handles_out);
// Adds new edges to the stack graph. You provide an array of `struct sg_edges` instances. A
// stack graph can contain at most one edge between any two nodes. It is not an error if you try
// to add an edge that already exists, but it won't have any effect on the graph.
void sg_stack_graph_add_edges(struct sg_stack_graph *graph,
size_t count,
const struct sg_edge *edges);
// Returns a reference to the array of source information in this stack graph. The resulting
// array pointer is only valid until the next call to any function that mutates the stack graph.
struct sg_source_infos sg_stack_graph_source_infos(const struct sg_stack_graph *graph);
// Adds new source information to the stack graph. You provide an array of `sg_node_source_info`
// instances. Any existing source information for any node mentioned in the array is overwritten.
void sg_stack_graph_add_source_infos(struct sg_stack_graph *graph,
size_t count,
const struct sg_node_source_info *infos);
// Returns a reference to the array of partial symbol stack content in a partial path arena. The
// resulting array pointer is only valid until the next call to any function that mutates the path
// arena.
struct sg_partial_symbol_stack_cells sg_partial_path_arena_partial_symbol_stack_cells(const struct sg_partial_path_arena *partials);
// Adds new partial symbol stacks to the partial path arena. `count` is the number of partial
// symbol stacks you want to create. The content of each partial symbol stack comes from two
// arrays. The `lengths` array must have `count` elements, and provides the number of symbols in
// each partial symbol stack. The `symbols` array contains the contents of each of these partial
// symbol stacks in one contiguous array. Its length must be the sum of all of the counts in the
// `lengths` array. The `variables` array must have `count` elements, and provides the optional
// symbol stack variable for each partial symbol stack.
//
// You must also provide an `out` array, which must also have room for `count` elements. We will
// fill this array in with the `sg_partial_symbol_stack` instances for each partial symbol stack
// that is created.
void sg_partial_path_arena_add_partial_symbol_stacks(struct sg_partial_path_arena *partials,
size_t count,
const struct sg_partial_scoped_symbol *symbols,
const size_t *lengths,
const sg_symbol_stack_variable *variables,
struct sg_partial_symbol_stack *out);
// Returns a reference to the array of partial scope stack content in a partial path arena. The
// resulting array pointer is only valid until the next call to any function that mutates the
// partial path arena.
struct sg_partial_scope_stack_cells sg_partial_path_arena_partial_scope_stack_cells(const struct sg_partial_path_arena *partials);
// Adds new partial scope stacks to the partial path arena. `count` is the number of partial
// scope stacks you want to create. The content of each partial scope stack comes from three
// arrays. The `lengths` array must have `count` elements, and provides the number of scopes in
// each scope stack. The `scopes` array contains the contents of each of these scope stacks in
// one contiguous array. Its length must be the sum of all of the counts in the `lengths` array.
// The `variables` array must have `count` elements, and provides the optional scope stack
// variable for each partial scope stack.
//
// You must also provide an `out` array, which must also have room for `count` elements. We will
// fill this array in with the `sg_partial_scope_stack` instances for each partial scope stack
// that is created.
void sg_partial_path_arena_add_partial_scope_stacks(struct sg_partial_path_arena *partials,
size_t count,
const sg_node_handle *scopes,
const size_t *lengths,
const sg_scope_stack_variable *variables,
struct sg_partial_scope_stack *out);
// Returns a reference to the array of partial path edge list content in a partial path arena.
// The resulting array pointer is only valid until the next call to any function that mutates the
// partial path arena.
struct sg_partial_path_edge_list_cells sg_partial_path_arena_partial_path_edge_list_cells(const struct sg_partial_path_arena *partials);
// Adds new partial path edge lists to the partial path arena. `count` is the number of partial
// path edge lists you want to create. The content of each partial path edge list comes from two
// arrays. The `lengths` array must have `count` elements, and provides the number of edges in
// each partial path edge list. The `edges` array contains the contents of each of these partial
// path edge lists in one contiguous array. Its length must be the sum of all of the counts in
// the `lengths` array.
//
// You must also provide an `out` array, which must also have room for `count` elements. We will
// fill this array in with the `sg_partial_path_edge_list` instances for each partial path edge
// list that is created.
void sg_partial_path_arena_add_partial_path_edge_lists(struct sg_partial_path_arena *partials,
size_t count,
const struct sg_partial_path_edge *edges,
const size_t *lengths,
struct sg_partial_path_edge_list *out);
// Creates a new, empty sg_partial_path_list.
struct sg_partial_path_list *sg_partial_path_list_new(void);
void sg_partial_path_list_free(struct sg_partial_path_list *partial_path_list);
size_t sg_partial_path_list_count(const struct sg_partial_path_list *partial_path_list);
const struct sg_partial_path *sg_partial_path_list_paths(const struct sg_partial_path_list *partial_path_list);
// Finds all partial paths in a file that are _productive_ and _as complete as possible_, placing
// the result into the `partial_path_list` output parameter. You must free the path list when you
// are done with it by calling `sg_partial_path_list_done`.
//
// This function will not return until all reachable paths have been processed, so `graph` must
// already contain a complete stack graph. If you have a very large stack graph stored in some
// other storage system, and want more control over lazily loading only the necessary pieces, then
// you should use sg_forward_path_stitcher.
enum sg_result sg_partial_path_arena_find_partial_paths_in_file(const struct sg_stack_graph *graph,
struct sg_partial_path_arena *partials,
sg_file_handle file,
struct sg_partial_path_list *partial_path_list,
const size_t *cancellation_flag);
// Finds all complete paths reachable from a set of starting nodes, placing the result into the
// `path_list` output parameter. You must free the path list when you are done with it by calling
// `sg_path_list_done`.
//
// This function will not return until all reachable paths have been processed, so `graph` must
// already contain a complete stack graph. If you have a very large stack graph stored in some
// other storage system, and want more control over lazily loading only the necessary pieces, then
// you should use sg_forward_path_stitcher.
enum sg_result sg_partial_path_arena_find_all_complete_paths(const struct sg_stack_graph *graph,
struct sg_partial_path_arena *partials,
size_t starting_node_count,
const sg_node_handle *starting_nodes,
struct sg_partial_path_list *path_list,
const size_t *cancellation_flag);
// Returns a reference to the array of partial path data in this partial path database. The
// resulting array pointer is only valid until the next call to any function that mutates the
// partial path database.
struct sg_partial_paths sg_partial_path_database_partial_paths(const struct sg_partial_path_database *db);
// Adds new partial paths to the partial path database. `paths` is the array of partial paths
// that you want to add; `count` is the number of them.
//
// We copy the partial path content into the partial path database. The array you pass in does
// not need to outlive the call to this function.
//
// You should take care not to add a partial path to the database multiple times. This won't
// cause an _error_, in that nothing will break, but it will probably cause you to get duplicate
// paths from the path-stitching algorithm.
//
// You must also provide an `out` array, which must also have room for `count` elements. We will
// fill this array in with the `sg_partial_path_edge_list` instances for each partial path edge
// list that is created.
void sg_partial_path_database_add_partial_paths(const struct sg_stack_graph *graph,
struct sg_partial_path_arena *partials,
struct sg_partial_path_database *db,
size_t count,
const struct sg_partial_path *paths,
sg_partial_path_handle *out);
// Determines which nodes in the stack graph are “local”, taking into account the partial paths in
// this database. The result is valid until the next call to this function, or until the database
// is freed.
//
// A local node has no partial path that connects it to the root node in either direction. That
// means that it cannot participate in any paths that leave the file.
//
// This method is meant to be used at index time, to calculate the set of nodes that are local
// after having just calculated the set of partial paths for the file.
void sg_partial_path_database_find_local_nodes(struct sg_partial_path_database *db);
// Marks that a list of stack graph nodes are local.
//
// This method is meant to be used at query time. You will have precalculated the set of local
// nodes for a file at index time; at query time, you will load this information from your storage
// layer and use this method to update our internal view of which nodes are local.
void sg_partial_path_database_mark_local_nodes(struct sg_partial_path_database *db,
size_t count,
const sg_node_handle *nodes);
// Returns a reference to the set of stack graph nodes that are local, according to this database
// of partial paths. The resulting set is only valid until the next call to any function that
// mutates the partial path database.
struct sg_node_handle_set sg_partial_path_database_local_nodes(const struct sg_partial_path_database *db);
// Creates a new forward partial path stitcher that is "seeded" with a set of starting stack graph
// nodes. The path stitcher will be set up to find complete paths only.
struct sg_forward_partial_path_stitcher *sg_forward_partial_path_stitcher_from_nodes(const struct sg_stack_graph *graph,
struct sg_partial_path_arena *partials,
size_t count,
const sg_node_handle *starting_nodes);
// Creates a new forward partial path stitcher that is "seeded" with a set of initial partial
// paths.
struct sg_forward_partial_path_stitcher *sg_forward_partial_path_stitcher_from_partial_paths(const struct sg_stack_graph *graph,
struct sg_partial_path_arena *partials,
size_t count,
const struct sg_partial_path *initial_partial_paths);
// Sets whether similar path detection should be enabled during path stitching. Paths are similar
// if start and end node, and pre- and postconditions are the same. The presence of similar paths
// can lead to exponential blow up during path stitching. Similar path detection is disabled by
// default because of the accociated preformance cost.
void sg_forward_partial_path_stitcher_set_similar_path_detection(struct sg_forward_partial_path_stitcher *stitcher,
bool detect_similar_paths);
// Sets the maximum amount of work that can be performed during each phase of the algorithm. By
// bounding our work this way, you can ensure that it's not possible for our CPU-bound algorithm
// to starve any worker threads or processes that you might be using. If you don't call this
// method, then we allow ourselves to process all of the extensions of all of the paths found in
// the previous phase, with no additional bound.
void sg_forward_partial_path_stitcher_set_max_work_per_phase(struct sg_forward_partial_path_stitcher *stitcher,
size_t max_work);
// Runs the next phase of the algorithm. We will have built up a set of incomplete partial paths
// during the _previous_ phase. Before calling this function, you must ensure that `db` contains
// all of the possible partial paths that we might want to extend any of those candidate partial
// paths with.
//
// After this method returns, you can retrieve a list of the (possibly incomplete) partial paths
// that were encountered during this phase via the `previous_phase_partial_paths` and
// `previous_phase_partial_paths_length` fields.
void sg_forward_partial_path_stitcher_process_next_phase(const struct sg_stack_graph *graph,
struct sg_partial_path_arena *partials,
struct sg_partial_path_database *db,
struct sg_forward_partial_path_stitcher *stitcher);
// Frees a forward path stitcher.
void sg_forward_partial_path_stitcher_free(struct sg_forward_partial_path_stitcher *stitcher);
#ifdef __cplusplus
} // extern "C"
#endif // __cplusplus
#endif /* STACK_GRAPHS_H_ */