Struct PolicyContext

pub struct PolicyContext {
    name: Identifier,
    inner: Arc<dyn HasDiagnosticsBase>,
}

A context for a named policy.

You may call any method and access any field defined on Context. In addition all diagnostics messages emitted from this struct will carry the name of the policy.

See the module level documentation for more information on diagnostic context management.

Fields

name: Identifier

inner: Arc<dyn HasDiagnosticsBase>

Implementations

impl PolicyContext

pub fn named_combinator<A>( self: Arc<Self>, name: impl Into<Identifier>, computation: impl FnOnce(Arc<CombinatorContext>) -> A, ) -> A

Add a named combinator to the diagnostic context.

See the module level documentation for more information on diagnostic context management.

pub fn named_controller<A>( self: Arc<Self>, id: Endpoint, policy: impl FnOnce(Arc<ControllerContext>) -> A, ) -> A

Run the computation in the diagnostic context of this controller

See the module level documentation for more information on diagnostic context management.

pub fn controller_contexts( self: &Arc<Self>, ) -> impl Iterator<Item = Arc<ControllerContext>>

Iterate over all defined controllers as contexts

Methods from Deref<Target = RootContext>

pub fn always_happens_before( &self, starting_points: impl IntoIterator<Item = GlobalNode>, is_checkpoint: impl FnMut(GlobalNode) -> bool, is_terminal: impl FnMut(GlobalNode) -> bool, ) -> Result<AlwaysHappensBefore>

Enforce that on every data flow path from the starting_points to is_terminal a node satisfying is_checkpoint is passed.

Fails if ctrl_id on a provided starting point is not found.

The return value contains some statistics information about the traversal. The property holds if AlwaysHappensBefore::holds is true.

Note that is_checkpoint and is_terminal will be called many times and should thus be efficient computations. In addition they should always return the same result for the same input.

pub fn associated_call_site(&self, node: GlobalNode) -> CallString

👎Deprecated: Use NodeExt::associated_call_site instead

Find the call string for the statement or function that produced this node.

pub fn consuming_call_sites( &self, node: GlobalNode, ) -> impl Iterator<Item = CallString> + '_

👎Deprecated: Use NodeQueries::consuming_call_sites instead

Call sites that consume this node directly. E.g. the outgoing edges.

pub fn controllers_by_name( &self, name: Identifier, ) -> impl Iterator<Item = Endpoint> + '_

Find all controllers that bare this name.

This function is intended for use in writing test cases. Actual policies should generally refrain from working with controller names, other than printing them in error messages or for debugging. Policies contingent on controller names are likely unsound.

pub fn controller_by_name(&self, name: Identifier) -> Result<Endpoint>

Find a singular controller with this name.

This function should only be used in tests as the same caveats apply as in Self::controllers_by_name.

Returns Err

If there is not exactly one controller of this name.

pub fn find_by_name(&self, name: impl AsRef<str>) -> Result<DefId>

Find a type, controller or function id by its name.

Since many often share the same name this can fail with too many candidates. To handle such cases use Self::find_by_path or Self::find_all_by_name.

pub fn find_all_by_name(&self, name: impl AsRef<str>) -> Result<&[DefId]>

Find all types, controllers and functions with this name.

pub fn find_by_path(&self, path: impl AsRef<[Identifier]>) -> Result<DefId>

Find a type, controller or function with this path.

pub fn emit_diagnostics_may_exit(&self, w: impl Write) -> Result<()>

Dispatch and drain all queued diagnostics, aborts the program if any of them demand failure.

pub fn emit_diagnostics(&self, w: impl Write) -> Result<bool>

Dispatch and drain all queued diagnostics without aborting the program.

pub fn all_nodes(&self) -> impl Iterator<Item = GlobalNode> + '_

Returns all nodes that are in any of the PDGs

pub fn roots_where<'a>( &'a self, f: impl Fn(GlobalNode) -> bool + 'a, ) -> impl Iterator<Item = GlobalNode> + 'a

Return nodes that satisfy the predicate and which have no ancestors that satisfy the same predicate.

pub fn report_marker_if_absent(&self, marker: Marker)

Emit a warning if this marker was not found in the source code.

pub fn flows_to( &self, src: impl IntoIterGlobalNodes, sink: impl IntoIterGlobalNodes, edge_type: EdgeSelection, ) -> bool

👎Deprecated: Use NodeQueries::flows_to instead

Returns whether a node flows to a node through the configured edge type.

Nodes do not flow to themselves. CallArgument nodes do flow to their respective CallSites.

If you use flows_to with EdgeSelection::Control, you might want to consider using RootContext::has_ctrl_influence, which additionally considers intermediate nodes which the src node has data flow to and has ctrl influence on the sink.

pub fn controller_argument( &self, ctrl_id: Endpoint, index: u32, ) -> Option<GlobalNode>

Find the node that represents the indexth argument of the controller ctrl_id.

Returns None

If the controller with this id does not exist or the controller has fewer than index arguments.

pub fn has_ctrl_influence( &self, influencer: impl IntoIterGlobalNodes, target: impl IntoIterGlobalNodes, ) -> bool

Returns whether there is direct control flow influence from influencer to sink, or there is some node which is data-flow influenced by influencer and has direct control flow influence on target. Or as expressed in code:

some n where self.flows_to(influencer, n, EdgeSelection::Data) && self.flows_to(n, target, EdgeSelection::Control).

pub fn influencers( &self, sink: impl IntoIterGlobalNodes, edge_type: EdgeSelection, ) -> impl Iterator<Item = GlobalNode> + '_

Returns iterator over all Nodes that influence the given sink Node.

Does not return the input node. A CallSite sink will return all of the associated CallArgument nodes.

pub fn influencees( &self, src: impl IntoIterGlobalNodes, edge_type: EdgeSelection, ) -> impl Iterator<Item = GlobalNode> + '_

Returns iterator over all Nodes that are influenced by the given src Node.

Does not return the input node. A CallArgument src will return the associated CallSite.

pub fn get_node_types(&self, node: GlobalNode) -> &[DefId]

👎Deprecated: Use NodeExt::types instead

Get the type(s) of a Node.

pub fn has_marker(&self, marker: Marker, node: GlobalNode) -> bool

👎Deprecated: Use NodeExt::has_marker instead

Returns whether the given Node has the marker applied to it directly or via its type.

pub fn all_nodes_for_ctrl( &self, ctrl_id: Endpoint, ) -> impl Iterator<Item = GlobalNode> + '_

Returns all DataSources, DataSinks, and CallSites for a Controller as Nodes.

pub fn srcs_with_type( &self, ctrl_id: Endpoint, t: DefId, ) -> impl Iterator<Item = GlobalNode> + '_

Returns an iterator over the data sources within controller c that have type t.

pub fn roots( &self, ctrl_id: Endpoint, edge_type: EdgeSelection, ) -> impl Iterator<Item = GlobalNode> + '_

Returns an iterator over all nodes that do not have any influencers of the given edge_type.

pub fn desc(&self) -> &ProgramDescription

Returns the input ProgramDescription.

pub fn otypes(&self, id: TypeId) -> &[TypeId]

Returns all the type alias annotation for a given type

pub fn marked_type(&self, marker: Marker) -> &[DefId]

Return all types that are marked with marker

pub fn any_flows( &self, from: &[GlobalNode], to: &[GlobalNode], edge_type: EdgeSelection, ) -> Option<(GlobalNode, GlobalNode)>

Return an example pair for a flow from an source from from to a sink in to if any exist.

pub fn all_controllers(&self) -> impl Iterator<Item = (Endpoint, &SPDG)>

Iterate over all defined controllers

pub fn describe_def(&self, def_id: DefId) -> DisplayDef<'_>

Returns a DisplayDef for the given def_id

pub fn describe_node(&self, node: GlobalNode) -> DisplayNode<'_>

👎Deprecated: Use NodeExt::describe instead

Returns a DisplayNode for the given Node

pub fn inputs_of(&self, call_string: CallString) -> NodeCluster

Return which data is being read from for the modification performed at this location

pub fn outputs_of(&self, call_string: CallString) -> NodeCluster

Return which data is being written to at this location

pub fn node_info(&self, node: GlobalNode) -> &NodeInfo

👎Deprecated: Use NodeExt::info instead

Retrieve metadata about a node.

pub fn instruction_at_node(&self, node: GlobalNode) -> &InstructionInfo

Retrieve metadata about the instruction executed by a specific node.

pub fn successors( &self, node: GlobalNode, ) -> impl Iterator<Item = GlobalNode> + '_

👎Deprecated: Use NodeExt::successors instead

Return the immediate successors of this node

pub fn predecessors( &self, node: GlobalNode, ) -> impl Iterator<Item = GlobalNode> + '_

👎Deprecated: Use NodeExt::predecessors instead

Return the immediate predecessors of this node

pub fn get_location(&self, node: GlobalNode) -> &Span

👎Deprecated: Use NodeExt::get_location instead

Get the span of a node

pub fn named_policy<A>( self: Arc<Self>, name: impl Into<Identifier>, policy: impl FnOnce(Arc<PolicyContext>) -> A, ) -> A

Add a policy to the diagnostic context.

See the module level documentation for more information on diagnostic context management.

pub fn named_controller<A>( self: Arc<Self>, id: Endpoint, policy: impl FnOnce(Arc<ControllerContext>) -> A, ) -> A

Run the computation in the diagnostic context of this controller

See the module level documentation for more information on diagnostic context management.

pub fn named_combinator<A>( self: Arc<Self>, name: impl Into<Identifier>, computation: impl FnOnce(Arc<CombinatorContext>) -> A, ) -> A

Nest another named combinator into the diagnostic context.

See the module level documentation for more information on diagnostic context management.

pub fn controller_contexts( self: &Arc<Self>, ) -> impl Iterator<Item = Arc<ControllerContext>>

Iterate over all defined controllers as contexts

Trait Implementations

impl HasDiagnosticsBase for PolicyContext

fn record(&self, diagnostic: Diagnostic)

Base function for recording new diagnostics.

fn as_ctx(&self) -> &RootContext

Access to Context, usually also available via std::ops::Deref.

impl Deref for PolicyContext

type Target = RootContext

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.