Module swipl::context

Prolog contexts.

As you interact with SWI-Prolog, the underlying prolog engine moves into different states, where different things are allowed. We keep track of this underlying state through Context objects.

Currently, there’s four kind of states that we keep track of:

• ActivatedEngine - this is the state an engine will be in when we just created it. If you’re directly working with engines, this will be your initial state.
• Unmanaged - this is the state an engine will be in when prolog is calling into the rust library, for example, when a foreign predicate implemented in rust is being called.
• Framed - In any context, you can create a prolog frame. A prolog frame allows you to rewind the state of all prolog terms to their state at the time of frame creation.
• OpenCall - While calling into prolog, this is the context you’ll be in as you’re walking through the solutions. This is a special context where a lot of the normal features are disabled.

Contexts are either active or inactive. A context starts out as active, but as soon as you do something that creates a new context (create a frame, open a query), the context will become inactive. Once the created context is dropped, the original context will become active again.

With the exception of the OpenCall context, all contexts let you create new term refs, which are handles to data on the prolog stack. These term refs can only be created while the context is active. However, they can be manipulated as long as the context that created them exists. As soon as the context is dropped though, the Term will become invalid and trying to do anything with it will result in a compile error.

The OpenCall context is special in that no new terms are allowed to be created, nor are you allowed to open another query. It is however possible to create a new frame in this context, which would once again put you in a state where these things are possible. Of course, you’ll have to drop this frame before you’re able to manipulate the OpenCall context again (such as retrieving the next solution from the query).

Various operations may cause the underlying engine to go into an exceptional state. This is signaled by these operations returning an Err(PrologError::Exception). This means that a special exception term has been set. Most context operations are impossible while in this state, and attempting to perform them will result in a panic. Your options are either to return back into prolog (if you’re implementing a foreign predicate), which will then raise this exception in prolog, or to clear the exception.

Structs

• ActivatedEngine
  Context type for an active engine. This wraps an EngineActivation.
• Context
  A context that the underlying prolog engine is in.
• ExceptionTerm
  A term wrapper for the special exception term.
• Frame
  Context type for a prolog frame.
• GenericQueryableContextType
• TermListIterator
  An iterator over a term list.
• Unmanaged
  Context type for an unmanaged engine.

Traits

• ContextType
  A type of context.
• FrameableContextType
  A trait marker for context types for which it is safe to open frames.
• IntoPrologException
  Trait for turning errors into prolog exceptions
• QueryableContextType
  A trait marker for context types for which it is safe to open queries and create new term refs.

Functions

• prolog_catch_unwind^⚠
  Call the given function, converting panics into prolog exceptions.
• unmanaged_engine_context^⚠
  Create an unmanaged context for situations where the thread has an engine that rust doesn’t know about.

Type Aliases

• GenericQueryableContext