Class GuestThreads

java.lang.Object

thc.runtime.GuestThreads

public final class GuestThreads
extends Object

A carrier can suspend one guest in foreign code and enter a distinct bound callback.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static enum	GuestThreads.DeliveryPermission	This is execution permission, not the observable Haskell masking state.
static final class	GuestThreads.GuestEntry
static final class	GuestThreads.GuestThread
static final class	GuestThreads.PollState	Stable per-context/carrier cell, including between nested guest entries.
static final class	GuestThreads.PollStates	Carrier cells can be initialized before the Env-owned guest-thread service is patched.
static interface	GuestThreads.Wake

Constructor Summary

Constructors

Constructor	Description
GuestThreads(com.oracle.truffle.api.TruffleLanguage.Env env, ThreadLocal<MaskingState> maskingState)
GuestThreads(com.oracle.truffle.api.TruffleLanguage.Env env, ThreadLocal<MaskingState> maskingState, String hosting)
GuestThreads(com.oracle.truffle.api.TruffleLanguage.Env env, ThreadLocal<MaskingState> maskingState, String hosting, GuestThreads.PollStates pollStates)
GuestThreads(ThreadLocal<MaskingState> maskingState, CpuAffinity cpuAffinity, GuestThreads.Wake wake)
GuestThreads(ThreadLocal<MaskingState> maskingState, GuestThreads.Wake wake)

Method Summary

Modifier and Type	Method	Description
Thread	admissionOrigin()
long	allocationCounter()
static GuestThreadExtent	blocking(GuestThreadStatus status)	No guest entry means no Haskell thread to mark (also used by cell protocol tests).
long	capabilityCount()
void	checkEntryAllowed()
static void	checkpointCurrent(com.oracle.truffle.api.nodes.Node node)
void	close()
void	completeCurrent()
static GuestThreads	current(com.oracle.truffle.api.nodes.Node node)
long	currentId()	myThreadId# observes an existing guest entry; it never creates a new lifetime.
GuestThreadId	currentIdentity()
long	enterCurrent()
long	enterCurrent(MaskingState inheritedMask)
long	enterCurrent(MaskingState inheritedMask, boolean forked)
long	enterCurrent(MaskingState inheritedMask, boolean forked, boolean externalAsync)
long	enterCurrent(MaskingState inheritedMask, boolean forked, boolean externalAsync, Long capability)
GuestThreads.DeliveryPermission	enterForeign()	Only an exact safe declaration admits callbacks.
GuestThreads.DeliveryPermission	enterForeign(ForeignSafety safety)
GuestThreads.DeliveryPermission	enterForeignForDisposal()	Final retirement grants no callback authority and cannot begin a new guest operation.
boolean	finish(AsyncRequest request, AsyncRequestState state)
boolean	finish(AsyncRequest request, AsyncRequestState state, Throwable cause)
CpuAffinity	getCpuAffinity()
<T> T	hostEntry(com.oracle.truffle.api.nodes.Node node, Callable<T> action)
boolean	inForeignCallback()	An uncaught callback cannot carry its opaque foreign caller as a guest continuation.
boolean	interruptibleForeignPending()	Inspect, never claim, a request while an interruptible open owns foreign execution.
boolean	isCurrentBound()
boolean	isLoom()
Object	label(GuestThreadId identity)
void	label(GuestThreadId identity, Object bytes)
void	leaveCurrent()
void	leaveCurrent(GuestThreadStatus outcome)	Called by the target in the same finally block that ends its guest action.
void	leaveForeign(GuestThreads.DeliveryPermission previous)
Long	liveJavaId(GuestThreadId identity)	Snapshot only: eventual dispatch checks the same identity atomically with enqueue.
MainThreadWeakKey	mainThreadRegistration()
boolean	needsHosting()
Thread	newThread(com.oracle.truffle.api.TruffleLanguage.Env env, Runnable task, Long capability, com.oracle.truffle.api.nodes.Node node)
static boolean	ordinaryPollEnabled(com.oracle.truffle.api.nodes.Node node)	Only ordinary polls speculate.
boolean	pause(AsyncRequest request)	Remove an uncommitted outbound throwTo while its sender handles an async exception.
AsyncRequest	poll(com.oracle.truffle.api.nodes.Node node)
AsyncRequest	poll(com.oracle.truffle.api.nodes.Node node, boolean interruptible)
static AsyncRequest	pollCurrent(com.oracle.truffle.api.nodes.Node node, boolean interruptible)	Java-callable poll for bytecode roots; it never delivers from a wake action.
static AsyncRequest	pollCurrentWithoutYield(com.oracle.truffle.api.nodes.Node node, boolean interruptible)	Used under commit/owner locks; scheduling yield happens before acquiring them.
static AsyncRequest	pollMandatoryCurrent(com.oracle.truffle.api.nodes.Node node, boolean interruptible)	Self throwTo is synchronous even while the single-origin assumption is valid.
GuestThreads.PollState	pollState(Thread thread)
long	registerCurrent()
void	registerMainThread(MainThreadWeakKey key)
GuestThreadId	requireIdentity(Object value)	A retained completed identity remains valid; a same-number fabricated object does not.
void	resume(AsyncRequest request)	Resume the same logical request after the sender's caught continuation resumes.
AsyncRequest	send(long targetId, Object payload)	The sender waits on this token; safepoint observation is not delivery.
AsyncRequest	send(GuestThreadId identity, Object payload)
void	setAllocationCounter(long value)
void	setAllocationCounter(long value, GuestThreadId identity)
void	setCapabilityCount(long count)
boolean	setCurrentExternalAsync(boolean enabled)	Scope host-call admission without changing queued requests or the guest lifetime.
Object[]	snapshot()	Independent snapshot including retained completed identities under the registry lock.
void	startThread(Thread thread)
GuestThreadStatus	status(GuestThreadId identity)
void	stopHostedThreads()

Methods inherited from class Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

GuestThreads

public GuestThreads(ThreadLocal<MaskingState> maskingState,
 GuestThreads.Wake wake)

GuestThreads

public GuestThreads(ThreadLocal<MaskingState> maskingState,
 CpuAffinity cpuAffinity,
 GuestThreads.Wake wake)

GuestThreads

public GuestThreads(com.oracle.truffle.api.TruffleLanguage.Env env,
 ThreadLocal<MaskingState> maskingState)

GuestThreads

public GuestThreads(com.oracle.truffle.api.TruffleLanguage.Env env,
 ThreadLocal<MaskingState> maskingState,
 String hosting)

GuestThreads

public GuestThreads(com.oracle.truffle.api.TruffleLanguage.Env env,
 ThreadLocal<MaskingState> maskingState,
 String hosting,
 GuestThreads.PollStates pollStates)

Method Details

getCpuAffinity

public CpuAffinity getCpuAffinity()

isLoom

public boolean isLoom()

needsHosting

public boolean needsHosting()

hostEntry

public <T> T hostEntry(com.oracle.truffle.api.nodes.Node node,
 Callable<T> action)

admissionOrigin

public Thread admissionOrigin()

checkEntryAllowed

public void checkEntryAllowed()

newThread

public Thread newThread(com.oracle.truffle.api.TruffleLanguage.Env env,
 Runnable task,
 Long capability,
 com.oracle.truffle.api.nodes.Node node)

startThread

public void startThread(Thread thread)

stopHostedThreads

public void stopHostedThreads()

pollState

public GuestThreads.PollState pollState(Thread thread)

capabilityCount

public long capabilityCount()

setCapabilityCount

public void setCapabilityCount(long count)

registerMainThread

public void registerMainThread(MainThreadWeakKey key)

mainThreadRegistration

public MainThreadWeakKey mainThreadRegistration()

enterForeign

public GuestThreads.DeliveryPermission enterForeign()

Only an exact safe declaration admits callbacks.

enterForeign

public GuestThreads.DeliveryPermission enterForeign(ForeignSafety safety)

enterForeignForDisposal

public GuestThreads.DeliveryPermission enterForeignForDisposal()

Final retirement grants no callback authority and cannot begin a new guest operation.

leaveForeign

public void leaveForeign(GuestThreads.DeliveryPermission previous)

inForeignCallback

public boolean inForeignCallback()

An uncaught callback cannot carry its opaque foreign caller as a guest continuation.

enterCurrent

public long enterCurrent()

enterCurrent

public long enterCurrent(MaskingState inheritedMask)

enterCurrent

public long enterCurrent(MaskingState inheritedMask,
 boolean forked)

enterCurrent

public long enterCurrent(MaskingState inheritedMask,
 boolean forked,
 boolean externalAsync)

enterCurrent

public long enterCurrent(MaskingState inheritedMask,
 boolean forked,
 boolean externalAsync,
 Long capability)

registerCurrent

public long registerCurrent()

setCurrentExternalAsync

public boolean setCurrentExternalAsync(boolean enabled)

Scope host-call admission without changing queued requests or the guest lifetime.

currentId

public long currentId()

myThreadId# observes an existing guest entry; it never creates a new lifetime.

currentIdentity

public GuestThreadId currentIdentity()

allocationCounter

public long allocationCounter()

setAllocationCounter

public void setAllocationCounter(long value)

requireIdentity

public GuestThreadId requireIdentity(Object value)

A retained completed identity remains valid; a same-number fabricated object does not.

setAllocationCounter

public void setAllocationCounter(long value,
 GuestThreadId identity)

snapshot

public Object[] snapshot()

Independent snapshot including retained completed identities under the registry lock.

isCurrentBound

public boolean isCurrentBound()

status

public GuestThreadStatus status(GuestThreadId identity)

label

public void label(GuestThreadId identity,
 Object bytes)

label

public Object label(GuestThreadId identity)

liveJavaId

public Long liveJavaId(GuestThreadId identity)

Snapshot only: eventual dispatch checks the same identity atomically with enqueue.

send

public AsyncRequest send(GuestThreadId identity,
 Object payload)

send

public AsyncRequest send(long targetId,
 Object payload)

The sender waits on this token; safepoint observation is not delivery.

poll

public AsyncRequest poll(com.oracle.truffle.api.nodes.Node node)

poll

public AsyncRequest poll(com.oracle.truffle.api.nodes.Node node,
 boolean interruptible)

interruptibleForeignPending

public boolean interruptibleForeignPending()

Inspect, never claim, a request while an interruptible open owns foreign execution.

leaveCurrent

public void leaveCurrent()

leaveCurrent

public void leaveCurrent(GuestThreadStatus outcome)

Called by the target in the same finally block that ends its guest action.

completeCurrent

public void completeCurrent()

close

public void close()

finish

public boolean finish(AsyncRequest request,
 AsyncRequestState state)

finish

public boolean finish(AsyncRequest request,
 AsyncRequestState state,
 Throwable cause)

pause

public boolean pause(AsyncRequest request)

Remove an uncommitted outbound throwTo while its sender handles an async exception.

resume

public void resume(AsyncRequest request)

Resume the same logical request after the sender's caught continuation resumes.

current

public static GuestThreads current(com.oracle.truffle.api.nodes.Node node)

blocking

public static GuestThreadExtent blocking(GuestThreadStatus status)

No guest entry means no Haskell thread to mark (also used by cell protocol tests).

pollCurrent

public static AsyncRequest pollCurrent(com.oracle.truffle.api.nodes.Node node,
 boolean interruptible)

Java-callable poll for bytecode roots; it never delivers from a wake action.

ordinaryPollEnabled

public static boolean ordinaryPollEnabled(com.oracle.truffle.api.nodes.Node node)

Only ordinary polls speculate. Calls and their capture handlers never do.

pollMandatoryCurrent

public static AsyncRequest pollMandatoryCurrent(com.oracle.truffle.api.nodes.Node node,
 boolean interruptible)

Self throwTo is synchronous even while the single-origin assumption is valid.

checkpointCurrent

public static void checkpointCurrent(com.oracle.truffle.api.nodes.Node node)

pollCurrentWithoutYield

public static AsyncRequest pollCurrentWithoutYield(com.oracle.truffle.api.nodes.Node node,
 boolean interruptible)

Used under commit/owner locks; scheduling yield happens before acquiring them.