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 pathc.rs
More file actions
1606 lines (1466 loc) · 65 KB
/
c.rs
File metadata and controls
1606 lines (1466 loc) · 65 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
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
// -*- coding: utf-8 -*-
// ------------------------------------------------------------------------------------------------
// Copyright © 2021, stack-graphs authors.
// Licensed under either of Apache License, Version 2.0, or MIT license, at your option.
// Please see the LICENSE-APACHE or LICENSE-MIT files in this distribution for license details.
// ------------------------------------------------------------------------------------------------
//! Defines a C API for working with stack graphs in other languages.
#![allow(non_camel_case_types)]
use std::convert::TryInto;
use std::sync::atomic::AtomicUsize;
use libc::c_char;
use crate::arena::Handle;
use crate::graph::File;
use crate::graph::InternedString;
use crate::graph::Node;
use crate::graph::NodeID;
use crate::graph::StackGraph;
use crate::graph::Symbol;
use crate::partial::PartialPath;
use crate::partial::PartialPathEdge;
use crate::partial::PartialPathEdgeList;
use crate::partial::PartialPaths;
use crate::partial::PartialScopeStack;
use crate::partial::PartialScopedSymbol;
use crate::partial::PartialSymbolStack;
use crate::stitching::Database;
use crate::stitching::DatabaseCandidates;
use crate::stitching::ForwardPartialPathStitcher;
use crate::stitching::GraphEdgeCandidates;
use crate::stitching::StitcherConfig;
use crate::CancellationError;
use crate::CancellationFlag;
/// Contains all of the nodes and edges that make up a stack graph.
pub struct sg_stack_graph {
pub inner: StackGraph,
}
/// Creates a new, initially empty stack graph.
#[no_mangle]
pub extern "C" fn sg_stack_graph_new() -> *mut sg_stack_graph {
Box::into_raw(Box::new(sg_stack_graph {
inner: StackGraph::new(),
}))
}
/// Frees a stack graph, and all of its contents.
#[no_mangle]
pub extern "C" fn sg_stack_graph_free(graph: *mut sg_stack_graph) {
drop(unsafe { Box::from_raw(graph) })
}
/// Manages the state of a collection of partial paths to be used in the path-stitching algorithm.
pub struct sg_partial_path_arena {
pub inner: PartialPaths,
}
/// Creates a new, initially empty partial path arena.
#[no_mangle]
pub extern "C" fn sg_partial_path_arena_new() -> *mut sg_partial_path_arena {
Box::into_raw(Box::new(sg_partial_path_arena {
inner: PartialPaths::new(),
}))
}
/// Frees a path arena, and all of its contents.
#[no_mangle]
pub extern "C" fn sg_partial_path_arena_free(partials: *mut sg_partial_path_arena) {
drop(unsafe { Box::from_raw(partials) })
}
/// 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.
pub struct sg_partial_path_database {
pub inner: Database,
}
/// Creates a new, initially empty partial path database.
#[no_mangle]
pub extern "C" fn sg_partial_path_database_new() -> *mut sg_partial_path_database {
Box::into_raw(Box::new(sg_partial_path_database {
inner: Database::new(),
}))
}
/// Frees a partial path database, and all of its contents.
#[no_mangle]
pub extern "C" fn sg_partial_path_database_free(db: *mut sg_partial_path_database) {
drop(unsafe { Box::from_raw(db) })
}
/// The null value for all of our handles.
pub const SG_NULL_HANDLE: u32 = 0;
/// The handle of an empty list.
pub const SG_LIST_EMPTY_HANDLE: u32 = 0xffffffff;
/// Describes in which direction the content of a deque is stored in memory.
#[repr(C)]
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum sg_deque_direction {
SG_DEQUE_FORWARDS,
SG_DEQUE_BACKWARDS,
}
impl Default for sg_deque_direction {
fn default() -> sg_deque_direction {
sg_deque_direction::SG_DEQUE_FORWARDS
}
}
/// Ensures all partial paths in the database are availabe in both forwards and backwards orientation.
#[no_mangle]
pub extern "C" fn sg_partial_path_database_ensure_both_directions(
db: *mut sg_partial_path_database,
partials: *mut sg_partial_path_arena,
) {
let db = unsafe { &mut (*db).inner };
let partials = unsafe { &mut (*partials).inner };
db.ensure_both_directions(partials);
}
/// Ensures all partial paths in the database are in forwards orientation.
#[no_mangle]
pub extern "C" fn sg_partial_path_database_ensure_forwards(
db: *mut sg_partial_path_database,
partials: *mut sg_partial_path_arena,
) {
let db = unsafe { &mut (*db).inner };
let partials = unsafe { &mut (*partials).inner };
db.ensure_forwards(partials);
}
//-------------------------------------------------------------------------------------------------
// Symbols
/// 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.
#[repr(C)]
pub struct sg_symbol {
pub symbol: *const c_char,
pub symbol_len: usize,
}
/// 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.
pub type sg_symbol_handle = u32;
/// 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.
#[repr(C)]
pub struct sg_symbols {
pub symbols: *const sg_symbol,
pub count: usize,
}
/// 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.
#[no_mangle]
pub extern "C" fn sg_stack_graph_symbols(graph: *const sg_stack_graph) -> sg_symbols {
let graph = unsafe { &(*graph).inner };
sg_symbols {
symbols: graph.symbols.as_ptr() as *const sg_symbol,
count: graph.symbols.len(),
}
}
/// 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.
#[no_mangle]
pub extern "C" fn sg_stack_graph_add_symbols(
graph: *mut sg_stack_graph,
count: usize,
symbols: *const c_char,
lengths: *const usize,
handles_out: *mut sg_symbol_handle,
) {
let graph = unsafe { &mut (*graph).inner };
let mut symbols = symbols as *const u8;
let lengths = unsafe { std::slice::from_raw_parts(lengths, count) };
let handles_out = unsafe {
std::slice::from_raw_parts_mut(handles_out as *mut Option<Handle<Symbol>>, count)
};
for i in 0..count {
let symbol = unsafe { std::slice::from_raw_parts(symbols, lengths[i]) };
handles_out[i] = match std::str::from_utf8(symbol) {
Ok(symbol) => Some(graph.add_symbol(symbol)),
Err(_) => None,
};
unsafe { symbols = symbols.add(lengths[i]) };
}
}
//-------------------------------------------------------------------------------------------------
// Interned strings
/// Arbitrary string content associated with some part of a stack graph.
#[repr(C)]
pub struct sg_string {
pub content: *const c_char,
pub length: usize,
}
/// 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.
pub type sg_string_handle = u32;
/// 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.
#[repr(C)]
pub struct sg_strings {
pub strings: *const sg_string,
pub count: usize,
}
/// 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.
#[no_mangle]
pub extern "C" fn sg_stack_graph_strings(graph: *const sg_stack_graph) -> sg_strings {
let graph = unsafe { &(*graph).inner };
sg_strings {
strings: graph.strings.as_ptr() as *const sg_string,
count: graph.strings.len(),
}
}
/// 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.
#[no_mangle]
pub extern "C" fn sg_stack_graph_add_strings(
graph: *mut sg_stack_graph,
count: usize,
strings: *const c_char,
lengths: *const usize,
handles_out: *mut sg_string_handle,
) {
let graph = unsafe { &mut (*graph).inner };
let mut strings = strings as *const u8;
let lengths = unsafe { std::slice::from_raw_parts(lengths, count) };
let handles_out = unsafe {
std::slice::from_raw_parts_mut(handles_out as *mut Option<Handle<InternedString>>, count)
};
for i in 0..count {
let string = unsafe { std::slice::from_raw_parts(strings, lengths[i]) };
handles_out[i] = match std::str::from_utf8(string) {
Ok(string) => Some(graph.add_string(string)),
Err(_) => None,
};
unsafe { strings = strings.add(lengths[i]) };
}
}
//-------------------------------------------------------------------------------------------------
// Files
/// 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.
#[repr(C)]
pub struct sg_file {
pub name: *const c_char,
pub name_len: usize,
}
/// 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.
pub type sg_file_handle = u32;
impl Into<Handle<File>> for sg_file_handle {
fn into(self) -> Handle<File> {
unsafe { std::mem::transmute(self) }
}
}
/// 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.
#[repr(C)]
pub struct sg_files {
pub files: *const sg_file,
pub count: usize,
}
/// 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.
#[no_mangle]
pub extern "C" fn sg_stack_graph_files(graph: *const sg_stack_graph) -> sg_files {
let graph = unsafe { &(*graph).inner };
sg_files {
files: graph.files.as_ptr() as *const sg_file,
count: graph.files.len(),
}
}
/// 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.
#[no_mangle]
pub extern "C" fn sg_stack_graph_add_files(
graph: *mut sg_stack_graph,
count: usize,
files: *const c_char,
lengths: *const usize,
handles_out: *mut sg_file_handle,
) {
let graph = unsafe { &mut (*graph).inner };
let mut files = files as *const u8;
let lengths = unsafe { std::slice::from_raw_parts(lengths, count) };
let handles_out =
unsafe { std::slice::from_raw_parts_mut(handles_out as *mut Option<Handle<File>>, count) };
for i in 0..count {
let file = unsafe { std::slice::from_raw_parts(files, lengths[i]) };
handles_out[i] = match std::str::from_utf8(file) {
Ok(file) => Some(graph.get_or_create_file(file)),
Err(_) => None,
};
unsafe { files = files.add(lengths[i]) };
}
}
//-------------------------------------------------------------------------------------------------
// Nodes
/// 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.
#[repr(C)]
#[derive(Clone, Copy, Default, Eq, PartialEq)]
pub struct sg_node_id {
pub file: sg_file_handle,
pub local_id: u32,
}
impl sg_node_id {
fn is_empty(self) -> bool {
self.file == 0 && self.local_id == 0
}
}
impl Into<NodeID> for sg_node_id {
fn into(self) -> NodeID {
unsafe { std::mem::transmute(self) }
}
}
/// The local_id of the singleton root node.
pub const SG_ROOT_NODE_ID: u32 = 1;
/// The local_id of the singleton "jump to scope" node.
pub const SG_JUMP_TO_NODE_ID: u32 = 2;
/// A node in a stack graph.
#[repr(C)]
#[derive(Clone)]
pub struct sg_node {
pub kind: sg_node_kind,
pub id: sg_node_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.
pub symbol: sg_symbol_handle,
/// 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.
pub scope: sg_node_id,
/// 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.
pub is_endpoint: bool,
}
impl Into<Node> for sg_node {
fn into(self) -> Node {
unsafe { std::mem::transmute(self) }
}
}
/// The different kinds of node that can appear in a stack graph.
#[repr(C)]
#[derive(Clone, Copy)]
pub 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,
}
/// A handle to a node in a stack graph. A zero handle represents a missing node.
pub type sg_node_handle = u32;
impl Into<Handle<Node>> for sg_node_handle {
fn into(self) -> Handle<Node> {
unsafe { std::mem::transmute(self) }
}
}
/// The handle of the singleton root node.
pub const SG_ROOT_NODE_HANDLE: sg_node_handle = 1;
/// The handle of the singleton "jump to scope" node.
pub const SG_JUMP_TO_NODE_HANDLE: sg_node_handle = 2;
/// 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.
#[repr(C)]
pub struct sg_nodes {
pub nodes: *const sg_node,
pub count: usize,
}
/// 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.
#[no_mangle]
pub extern "C" fn sg_stack_graph_nodes(graph: *const sg_stack_graph) -> sg_nodes {
let graph = unsafe { &(*graph).inner };
sg_nodes {
nodes: graph.nodes.as_ptr() as *const sg_node,
count: graph.nodes.len(),
}
}
/// 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.
#[no_mangle]
pub extern "C" fn sg_stack_graph_get_or_create_nodes(
graph: *mut sg_stack_graph,
count: usize,
nodes: *const sg_node,
handles_out: *mut sg_node_handle,
) {
let graph = unsafe { &mut (*graph).inner };
let nodes = unsafe { std::slice::from_raw_parts(nodes, count) };
let handles_out =
unsafe { std::slice::from_raw_parts_mut(handles_out as *mut Option<Handle<Node>>, count) };
for i in 0..count {
let node_id = nodes[i].id;
handles_out[i] = validate_node(graph, &nodes[i])
.map(|node| graph.get_or_create_node(node_id.into(), node));
}
}
fn validate_node_id(graph: &StackGraph, node_id: sg_node_id) -> Option<()> {
if node_id.file == 0 || node_id.file >= (graph.files.len() as u32) {
return None;
}
Some(())
}
fn validate_node(graph: &StackGraph, node: &sg_node) -> Option<Node> {
if matches!(
&node.kind,
sg_node_kind::SG_NODE_KIND_JUMP_TO | sg_node_kind::SG_NODE_KIND_ROOT
) {
// You can never add a singleton node, since there already is one!
return None;
}
// Every node must have a valid ID, which refers to an existing file.
validate_node_id(graph, node.id)?;
// Push and pop nodes must have a non-null symbol, and all other nodes must have a null symbol.
if (node.symbol != 0)
!= matches!(
&node.kind,
sg_node_kind::SG_NODE_KIND_POP_SCOPED_SYMBOL
| sg_node_kind::SG_NODE_KIND_POP_SYMBOL
| sg_node_kind::SG_NODE_KIND_PUSH_SCOPED_SYMBOL
| sg_node_kind::SG_NODE_KIND_PUSH_SYMBOL
)
{
return None;
}
// Push scoped symbol nodes must have a non-null scope, and all other nodes must have a null
// scope.
if (node.scope.is_empty())
== matches!(&node.kind, sg_node_kind::SG_NODE_KIND_PUSH_SCOPED_SYMBOL)
{
return None;
}
Some(node.clone().into())
}
//-------------------------------------------------------------------------------------------------
// Edges
/// 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.)
#[repr(C)]
pub struct sg_edge {
pub source: sg_node_handle,
pub sink: sg_node_handle,
pub precedence: i32,
}
/// 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.
#[no_mangle]
pub extern "C" fn sg_stack_graph_add_edges(
graph: *mut sg_stack_graph,
count: usize,
edges: *const sg_edge,
) {
let graph = unsafe { &mut (*graph).inner };
let edges = unsafe { std::slice::from_raw_parts(edges, count) };
for i in 0..count {
let source = unsafe { std::mem::transmute(edges[i].source) };
let sink = unsafe { std::mem::transmute(edges[i].sink) };
graph.add_edge(source, sink, edges[i].precedence);
}
}
//-------------------------------------------------------------------------------------------------
// Source info
/// Contains information about a range of code in a source code file.
#[repr(C)]
#[derive(Clone, Copy, Default)]
pub struct sg_source_info {
/// The location in its containing file of the source code that this node represents.
pub span: sg_span,
/// The kind of syntax entity this node represents (e.g. `function`, `class`, `method`, etc.).
pub syntax_type: sg_string_handle,
/// The full content of the line containing this node in its source file.
pub containing_line: sg_string_handle,
/// 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".
pub definiens_span: sg_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`).
pub fully_qualified_name: sg_string_handle,
}
/// All of the position information that we have about a range of content in a source file
#[repr(C)]
#[derive(Clone, Copy, Default)]
pub struct sg_span {
pub start: sg_position,
pub end: sg_position,
}
/// All of the position information that we have about a character in a source file
#[repr(C)]
#[derive(Clone, Copy, Default)]
pub struct sg_position {
/// The 0-indexed line number containing the character
pub line: usize,
/// The offset of the character within its containing line, expressed as both a UTF-8 byte
/// index and a UTF-16 code point index
pub column: sg_offset,
/// The UTF-8 byte indexes (within the file) of the start and end of the line containing the
/// character
pub containing_line: sg_utf8_bounds,
/// 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
pub trimmed_line: sg_utf8_bounds,
}
/// The offset of a character within a string (typically a line of source code), using several
/// different units
///
/// All offsets are 0-indexed.
#[repr(C)]
#[derive(Clone, Copy, Default)]
pub struct sg_offset {
/// The number of UTF-8-encoded bytes appearing before this character in the string
pub utf8_offset: usize,
/// The number of UTF-16 code units appearing before this character in the string
pub utf16_offset: usize,
/// The number of graphemes appearing before this character in the string
pub grapheme_offset: usize,
}
/// A half-open range identifying a range of characters in a string.
#[repr(C)]
#[derive(Clone, Copy, Default)]
pub struct sg_utf8_bounds {
/// The UTF-8 byte index of the first character in the range.
pub start: usize,
/// The UTF-8 byte index of the first character _after_ the range.
pub end: usize,
}
/// 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.
#[repr(C)]
pub struct sg_source_infos {
pub infos: *const sg_source_info,
pub count: usize,
}
/// 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.
#[no_mangle]
pub extern "C" fn sg_stack_graph_source_infos(graph: *const sg_stack_graph) -> sg_source_infos {
let graph = unsafe { &(*graph).inner };
sg_source_infos {
infos: graph.source_info.as_ptr() as *const sg_source_info,
count: graph.source_info.len(),
}
}
/// 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.
#[repr(C)]
#[derive(Clone, Copy)]
pub struct sg_node_source_info {
pub node: sg_node_handle,
pub source_info: sg_source_info,
}
/// 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.
#[no_mangle]
pub extern "C" fn sg_stack_graph_add_source_infos(
graph: *mut sg_stack_graph,
count: usize,
infos: *const sg_node_source_info,
) {
let graph = unsafe { &mut (*graph).inner };
let infos = unsafe { std::slice::from_raw_parts(infos, count) };
for i in 0..count {
let node = unsafe { std::mem::transmute(infos[i].node) };
let info = graph.source_info_mut(node);
*info = unsafe { std::mem::transmute(infos[i].source_info) };
}
}
//-------------------------------------------------------------------------------------------------
// Partial symbol stacks
/// Represents an unknown list of scoped symbols.
pub type sg_symbol_stack_variable = u32;
/// A symbol with an unknown, but possibly empty, list of exported scopes attached to it.
#[repr(C)]
#[derive(Clone, Copy, Eq, PartialEq)]
pub struct sg_partial_scoped_symbol {
pub symbol: sg_symbol_handle,
pub scopes: sg_partial_scope_stack,
}
impl Into<PartialScopedSymbol> for sg_partial_scoped_symbol {
fn into(self) -> PartialScopedSymbol {
unsafe { std::mem::transmute(self) }
}
}
/// 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.)
#[repr(C)]
#[derive(Clone, Copy, Default, Eq, PartialEq)]
pub 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.
pub cells: sg_partial_symbol_stack_cell_handle,
pub direction: sg_deque_direction,
pub length: u32,
/// 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.)
pub variable: sg_symbol_stack_variable,
}
impl From<PartialSymbolStack> for sg_partial_symbol_stack {
fn from(stack: PartialSymbolStack) -> sg_partial_symbol_stack {
unsafe { std::mem::transmute(stack) }
}
}
/// 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.
pub type sg_partial_symbol_stack_cell_handle = u32;
/// An element of a partial symbol stack.
#[repr(C)]
pub struct sg_partial_symbol_stack_cell {
/// The partial scoped symbol at this position in the partial symbol stack.
pub head: sg_partial_scoped_symbol,
/// The handle of the next element in the partial symbol stack, or SG_LIST_EMPTY_HANDLE if this
/// is the last element.
pub tail: sg_partial_symbol_stack_cell_handle,
/// The handle of the reversal of this partial scope stack.
pub reversed: sg_partial_symbol_stack_cell_handle,
}
/// The array of all of the partial symbol stack content in a partial path arena.
#[repr(C)]
pub struct sg_partial_symbol_stack_cells {
pub cells: *const sg_partial_symbol_stack_cell,
pub count: usize,
}
/// 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.
#[no_mangle]
pub extern "C" fn sg_partial_path_arena_partial_symbol_stack_cells(
partials: *const sg_partial_path_arena,
) -> sg_partial_symbol_stack_cells {
let partials = unsafe { &(*partials).inner };
sg_partial_symbol_stack_cells {
cells: partials.partial_symbol_stacks.as_ptr() as *const sg_partial_symbol_stack_cell,
count: partials.partial_symbol_stacks.len(),
}
}
/// 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.
#[no_mangle]
pub extern "C" fn sg_partial_path_arena_add_partial_symbol_stacks(
partials: *mut sg_partial_path_arena,
count: usize,
mut symbols: *const sg_partial_scoped_symbol,
lengths: *const usize,
variables: *const sg_symbol_stack_variable,
out: *mut sg_partial_symbol_stack,
) {
let partials = unsafe { &mut (*partials).inner };
let lengths = unsafe { std::slice::from_raw_parts(lengths, count) };
let variables = unsafe { std::slice::from_raw_parts(variables, count) };
let out = unsafe { std::slice::from_raw_parts_mut(out, count) };
for i in 0..count {
let length = lengths[i];
let symbols_slice = unsafe { std::slice::from_raw_parts(symbols, length) };
let mut stack = if variables[i] == 0 {
PartialSymbolStack::empty()
} else {
PartialSymbolStack::from_variable(variables[i].try_into().unwrap())
};
for j in 0..length {
let symbol = symbols_slice[j].into();
stack.push_back(partials, symbol);
}
// We pushed the edges onto the list in reverse order. Requesting a forwards iterator
// before we return ensures that it will also be available in forwards order.
let _ = stack.iter(partials);
out[i] = stack.into();
unsafe { symbols = symbols.add(length) };
}
}
//-------------------------------------------------------------------------------------------------
// Partial scope stacks
/// Represents an unknown list of exported scopes.
pub type sg_scope_stack_variable = u32;
/// 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.
#[repr(C)]
#[derive(Clone, Copy, Default, Eq, PartialEq)]
pub 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.
pub cells: sg_partial_scope_stack_cell_handle,
pub direction: sg_deque_direction,
pub length: u32,
/// 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.)
pub variable: sg_scope_stack_variable,
}
impl From<PartialScopeStack> for sg_partial_scope_stack {
fn from(stack: PartialScopeStack) -> sg_partial_scope_stack {
unsafe { std::mem::transmute(stack) }
}
}
/// 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.
pub type sg_partial_scope_stack_cell_handle = u32;
/// An element of a partial scope stack.
#[repr(C)]
pub struct sg_partial_scope_stack_cell {
/// The exported scope at this position in the partial scope stack.
pub head: sg_node_handle,
/// The handle of the next element in the partial scope stack, or SG_LIST_EMPTY_HANDLE if this
/// is the last element.
pub tail: sg_partial_scope_stack_cell_handle,
/// The handle of the reversal of this partial scope stack.
pub reversed: sg_partial_scope_stack_cell_handle,
}
/// The array of all of the partial scope stack content in a partial path arena.
#[repr(C)]
pub struct sg_partial_scope_stack_cells {
pub cells: *const sg_partial_scope_stack_cell,
pub count: usize,
}
/// 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.
#[no_mangle]
pub extern "C" fn sg_partial_path_arena_partial_scope_stack_cells(
partials: *const sg_partial_path_arena,
) -> sg_partial_scope_stack_cells {
let partials = unsafe { &(*partials).inner };
sg_partial_scope_stack_cells {
cells: partials.partial_scope_stacks.as_ptr() as *const sg_partial_scope_stack_cell,
count: partials.partial_scope_stacks.len(),
}
}
/// 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.
#[no_mangle]
pub extern "C" fn sg_partial_path_arena_add_partial_scope_stacks(
partials: *mut sg_partial_path_arena,
count: usize,
mut scopes: *const sg_node_handle,
lengths: *const usize,
variables: *const sg_scope_stack_variable,
out: *mut sg_partial_scope_stack,
) {
let partials = unsafe { &mut (*partials).inner };
let lengths = unsafe { std::slice::from_raw_parts(lengths, count) };
let variables = unsafe { std::slice::from_raw_parts(variables, count) };
let out = unsafe { std::slice::from_raw_parts_mut(out, count) };
for i in 0..count {
let length = lengths[i];
let scopes_slice = unsafe { std::slice::from_raw_parts(scopes, length) };
let mut stack = if variables[i] == 0 {
PartialScopeStack::empty()
} else {
PartialScopeStack::from_variable(variables[i].try_into().unwrap())
};
for j in 0..length {
let node = scopes_slice[j].into();
stack.push_back(partials, node);
}
// We pushed the edges onto the list in reverse order. Requesting a forwards iterator
// before we return ensures that it will also be available in forwards order.
let _ = stack.iter_scopes(partials);
out[i] = stack.into();
unsafe { scopes = scopes.add(length) };
}
}
//-------------------------------------------------------------------------------------------------
// Partial edge lists
/// Details about one of the edges in a partial path
#[repr(C)]
#[derive(Clone, Copy, Eq, PartialEq)]
pub struct sg_partial_path_edge {
pub source_node_id: sg_node_id,
pub precedence: i32,
}
impl Into<PartialPathEdge> for sg_partial_path_edge {
fn into(self) -> PartialPathEdge {
unsafe { std::mem::transmute(self) }
}
}