public interface IJCListener
Implementations forward Java interface method calls to the CLR side by invoking one of
the raiseEvent or raiseEventConcurrent overloads. Event identification
supports two modes:
String. Convenient but incurs
a name-to-index resolution cost on every call.getEventIndex(String),
resolved once and cached by the caller. Preferred in high-frequency event paths as it
avoids the resolution overhead entirely.Two concurrency models are available:
raiseEvent overloads serialize all calls at the instance
level. Safe for all scenarios but may become a bottleneck when multiple events are
raised concurrently. For non-void methods the CLR handler must call
setReturnData(Object) before returning; the JVM retrieves the value via
getReturnData().raiseEventConcurrent overloads allow different events to
proceed in parallel. Each invocation is identified by a unique callId generated
internally. The CLR handler reads event data via getEventData(long) and sets
the return value via setReturnData(long, Object); the return value is delivered
directly as the return value of raiseEventConcurrent. If
setSynchronized(boolean) is set to true, concurrent calls fall back to
the synchronized model.| Modifier and Type | Method and Description |
|---|---|
Object[] |
extraData()
Returns the additional arguments associated with the current event.
|
Object[] |
extraData(long callId)
Returns the additional arguments associated with the call identified by
callId. |
int |
extraDataLength()
Returns the number of additional arguments associated with the current event.
|
int |
extraDataLength(long callId)
Returns the number of additional arguments associated with the call identified by
callId. |
Object |
getEventData()
Returns the primary data object associated with the current event.
|
Object |
getEventData(long callId)
Returns the primary data object associated with the given call identifier.
|
int |
getEventIndex(String eventName)
Returns the numeric index associated with the given event name.
|
Object |
getReturnData()
Returns the return value set by the CLR handler for the current event.
|
Object |
getReturnData(long callId)
Returns the return value set by the CLR handler with the call identified by
callId. |
boolean |
hasExtraData()
Returns
true if the current event has additional arguments beyond the primary
data object. |
boolean |
hasExtraData(long callId)
Returns
true if the call identified by callId has additional arguments
beyond the primary data object. |
void |
initRingSize(int ringSize)
Initializes the ring buffer size for this listener instance.
|
void |
raiseEvent(int eventIndex)
Raises the event identified by numeric index on the CLR side with no associated data.
|
void |
raiseEvent(int eventIndex,
Object e)
Raises the event identified by numeric index on the CLR side, passing a single data object.
|
void |
raiseEvent(int eventIndex,
Object e,
Object... objects)
Raises the event identified by numeric index on the CLR side, passing a primary data object
and additional arguments.
|
void |
raiseEvent(String eventName)
Raises the named event on the CLR side with no associated data.
|
void |
raiseEvent(String eventName,
Object e)
Raises the named event on the CLR side, passing a single data object.
|
void |
raiseEvent(String eventName,
Object e,
Object... objects)
Raises the named event on the CLR side, passing a primary data object and additional arguments.
|
Object |
raiseEventConcurrent(int eventIndex)
Raises the event identified by numeric index on the CLR side with no associated data.
|
Object |
raiseEventConcurrent(int eventIndex,
Object e)
Raises the event identified by numeric index on the CLR side, passing a single data object.
|
Object |
raiseEventConcurrent(int eventIndex,
Object e,
Object... objects)
Raises the event identified by numeric index on the CLR side, passing a primary data object
and additional arguments.
|
Object |
raiseEventConcurrent(String eventName)
Raises the named event on the CLR side with no associated data.
|
Object |
raiseEventConcurrent(String eventName,
Object e)
Raises the event identified by numeric index on the CLR side, passing a single data object.
|
Object |
raiseEventConcurrent(String eventName,
Object e,
Object... objects)
Raises the event identified by numeric index on the CLR side, passing a primary data object
and additional arguments.
|
void |
release()
Releases the native resources held by this listener and unregisters it from the
JCOBridge runtime.
|
void |
setEmitCollisionWarnings(boolean emitWarnings)
Sets whether collision warnings are emitted to stderr when a ring buffer slot collision
is detected.
|
void |
setReturnData(long callId,
Object retData)
Sets the return value that the CLR handler provides for the call identified by
callId. |
void |
setReturnData(Object retData)
Sets the return value that the CLR handler provides for the current event.
|
void |
setSynchronized(boolean forceSynchronized)
Forces all
raiseEventConcurrent calls to fall back to the synchronized model. |
void release()
int getEventIndex(String eventName)
The returned index can be passed to the index-based raiseEvent or
raiseEventConcurrent overloads to avoid name-lookup overhead in high-frequency
event paths. The index should be resolved once and cached by the caller.
eventName - the name of the event as registered on the CLR side.void setSynchronized(boolean forceSynchronized)
raiseEventConcurrent calls to fall back to the synchronized model.forceSynchronized - true to force synchronized execution.void setEmitCollisionWarnings(boolean emitWarnings)
true. Set to false to suppress warnings in
production environments where collisions are expected and monitored via JCListener.getCollisionCount().emitWarnings - true to enable warnings, false to suppress them.void initRingSize(int ringSize)
ringSize - the desired ring buffer size; will be rounded up to the next power of two.void raiseEvent(String eventName)
eventName - the name of the event to raise.void raiseEvent(int eventIndex)
eventIndex - the numeric index of the event to raise, as returned by
getEventIndex(String).void raiseEvent(String eventName, Object e)
eventName - the name of the event to raise.e - the data object associated with the event; accessible from the CLR
handler via getEventData().void raiseEvent(int eventIndex,
Object e)
eventIndex - the numeric index of the event to raise.e - the data object associated with the event; accessible from the CLR
handler via getEventData().void raiseEvent(String eventName, Object e, Object... objects)
eventName - the name of the event to raise.e - the primary data object associated with the event.objects - additional arguments forwarded to the CLR handler, accessible via
extraData().void raiseEvent(int eventIndex,
Object e,
Object... objects)
eventIndex - the numeric index of the event to raise.e - the primary data object associated with the event.objects - additional arguments forwarded to the CLR handler, accessible via
extraData().Object raiseEventConcurrent(String eventName)
setReturnData(long, Object), or null for void events.eventName - the name of the event to raise.null.Object raiseEventConcurrent(int eventIndex)
setReturnData(long, Object), or null for void events.eventIndex - the numeric index of the event to raise, as returned by
getEventIndex(String).null.Object raiseEventConcurrent(String eventName, Object e)
getEventData(long). Returns the value set by the CLR handler
via setReturnData(long, Object), or null for void events.eventName - the name of the event to raise.e - the data object associated with the event.null.Object raiseEventConcurrent(int eventIndex, Object e)
getEventData(long). Returns the value set by the CLR handler
via setReturnData(long, Object), or null for void events.eventIndex - the numeric index of the event to raise.e - the data object associated with the event.null.Object raiseEventConcurrent(String eventName, Object e, Object... objects)
setReturnData(long, Object), or null for
void events.eventName - the name of the event to raise.e - the primary data object associated with the event.objects - additional arguments forwarded to the CLR handler, accessible via
extraData(long).null.Object raiseEventConcurrent(int eventIndex, Object e, Object... objects)
setReturnData(long, Object), or null for
void events.eventIndex - the numeric index of the event to raise.e - the primary data object associated with the event.objects - additional arguments forwarded to the CLR handler, accessible via
extraData(long).null.Object getEventData()
raiseEvent overloads.null if no data was provided.boolean hasExtraData()
true if the current event has additional arguments beyond the primary
data object. For use with the synchronized raiseEvent overloads.true if extra data is available.int extraDataLength()
raiseEvent overloads.0 if none.Object[] extraData()
raiseEvent overloads.null if none was provided.Object getReturnData()
raiseEvent overloads.null if not set.void setReturnData(Object retData)
raiseEvent overloads.retData - the value to return to the JVM caller.Object getEventData(long callId)
raiseEventConcurrent.callId - the unique call identifier generated by raiseEventConcurrent.null if no data was provided.boolean hasExtraData(long callId)
true if the call identified by callId has additional arguments
beyond the primary data object.
Called by the CLR runtime to decide whether to fetch extra data.callId - the unique call identifier generated by raiseEventConcurrent.true if extra data is available.int extraDataLength(long callId)
callId.callId - the unique call identifier generated by raiseEventConcurrent.0 if none.Object[] extraData(long callId)
callId.callId - the unique call identifier generated by raiseEventConcurrent.null if none was provided.Object getReturnData(long callId)
callId.
Used from CLR since the value is returned directly by raiseEventConcurrent.callId - the unique call identifier generated by raiseEventConcurrent.null if not set.void setReturnData(long callId,
Object retData)
callId. The value is returned directly by raiseEventConcurrent.callId - the unique call identifier generated by raiseEventConcurrent.retData - the value to return to the JVM caller.