Detailed Description

Queries events on one of a processor's outputs.

For a processor with an output arity n, there exists n distinct pullables, namely one for each output pipe. Every pullable works roughly like a classical Iterator: it is possible to check whether new output events are available, and get one new output event.

However, contrarily to iterators, Pullables have two versions of each method: a soft and a hard version.

Soft methods make a single attempt at producing an output event. Since processors are connected in a chain, this generally means pulling events from the input in order to produce the output. However, if pulling the input produces no event, no output event can be produced. In such a case, hasNextSoft() will return a special value (MAYBE), and pullSoft() will return null. Soft methods can be seen a doing "one turn of the crank" on the whole chain of processors –whether or not this outputs something.
Hard methods are actually calls to soft methods until an output event is produced: the "crank" is turned as long as necessary to produce something. This means that one call to, e.g. pull() may consume more than one event from a processor's input. Therefore, calls to hasNext() never return MAYBE (only YES or NO), and pull() throws NoSuchElementException only if no event will ever be output in the future (this occurs, for example, when pulling events from a file, and the end of the file has been reached).

The lifecycle of a Pullable object is as follows:

One obtains a reference to one of a processor's pullables. This can be done explicitly, e.g. by calling Processor#getPullableOutput(int), or implicitly, for example through every call to Connector#connect(Processor...).
At various moments, one calls hasNextSoft() (or hasNext() to check if events are available - One calls pullSoft() (or pull() to produce the next available output event.

The Pullable interface extends the Iterator and Iterable interfaces. This means that an instance of Pullable can also be iterated over like this:

Pullable p = ...; 
for (Object o : p) {
  // Do something 
}

Note however that if p refers to a processor producing an infinite number of events, this loop will never terminate by itself.

For the same processor, mixing calls to soft and hard methods is discouraged. As a matter of fact, the Pullable's behaviour in such a situation is left undefined.

Author: Sylvain Hallé

Since: 0.1

Definition at line 85 of file Pullable.java.

Classes
class	PullableException
	A runtime exception indicating that something went wrong when attempting to check if a next event exists. More...
class	PullNotSupported
	Pullable object that throws an `UnsupportedOperationException` upon every call to each of its methods (except `getProcessor()`). More...
enum	NextStatus
	The "next" status of a `Pullable` object. More...

Public Member Functions
Object	pullSoft ()
	Attempts to pull an event from the source.
Object	pull ()
	Attempts to pull an event from the source.
Object	next ()
	Attempts to obtain an event from the source.
NextStatus	hasNextSoft ()
	Determines if an event can be pulled from the output.
boolean	hasNext ()
	Determines if an event can be pulled from the output, by trying "harder" than `hasNextSoft()`.
Processor	getProcessor ()
	Gets the processor instance this Pullable is linked to.
int	getPosition ()
	Gets the position this Pullable is associated to: 0 is the first input (or output), 1 the second, etc.
void	start ()
	Starts the pullable.
void	stop ()
	Stops the pullable.
void	dispose ()
	Tells this pullable that methods `pull()`, `pullSoft()`, `hasNext()` and `hasNextSoft()` will not be called anymore.

Member Function Documentation

◆ dispose()

void ca.uqac.lif.cep.Pullable.dispose ( )

Tells this pullable that methods pull(), pullSoft(), hasNext() and hasNextSoft() will not be called anymore.

For some types of pullables, this can be used as a cue to free some resources (such as threads). The behaviour of these four methods after dispose() has been called is undefined. In future versions, it is possible that an exception will be thrown in such a case.

Implemented in ca.uqac.lif.cep.AsynchronousProcessor.OutputPullable, ca.uqac.lif.cep.functions.ApplyFunctionPartial.OutputPullable, ca.uqac.lif.cep.GroupProcessor.ProxyPullable, ca.uqac.lif.cep.Pullable.PullNotSupported, ca.uqac.lif.cep.SynchronousProcessor.OutputPullable, ca.uqac.lif.cep.tmf.Divert.DivertPullable, ca.uqac.lif.cep.tmf.Multiplex.MuxPullable, ca.uqac.lif.cep.tmf.Tank.QueuePullable, ca.uqac.lif.cep.TypedPullable< T >, and ca.uqac.lif.cep.UniformProcessor.UnaryPullable.

◆ getPosition()

int ca.uqac.lif.cep.Pullable.getPosition ( )

Gets the position this Pullable is associated to: 0 is the first input (or output), 1 the second, etc.

Returns: The position

Implemented in ca.uqac.lif.cep.AsynchronousProcessor.OutputPullable, ca.uqac.lif.cep.functions.ApplyFunctionPartial.OutputPullable, ca.uqac.lif.cep.GroupProcessor.ProxyPullable, ca.uqac.lif.cep.Pullable.PullNotSupported, ca.uqac.lif.cep.SynchronousProcessor.OutputPullable, ca.uqac.lif.cep.tmf.Divert.DivertPullable, ca.uqac.lif.cep.tmf.Multiplex.MuxPullable, ca.uqac.lif.cep.tmf.Tank.QueuePullable, ca.uqac.lif.cep.TypedPullable< T >, and ca.uqac.lif.cep.UniformProcessor.UnaryPullable.

◆ getProcessor()

Processor ca.uqac.lif.cep.Pullable.getProcessor ( )

Gets the processor instance this Pullable is linked to.

Returns: The processor

Implemented in ca.uqac.lif.cep.AsynchronousProcessor.OutputPullable, ca.uqac.lif.cep.functions.ApplyFunctionPartial.OutputPullable, ca.uqac.lif.cep.GroupProcessor.ProxyPullable, ca.uqac.lif.cep.Pullable.PullNotSupported, ca.uqac.lif.cep.SynchronousProcessor.OutputPullable, ca.uqac.lif.cep.tmf.Divert.DivertPullable, ca.uqac.lif.cep.tmf.Multiplex.MuxPullable, ca.uqac.lif.cep.tmf.Tank.QueuePullable, ca.uqac.lif.cep.TypedPullable< T >, and ca.uqac.lif.cep.UniformProcessor.UnaryPullable.

◆ hasNext()

boolean ca.uqac.lif.cep.Pullable.hasNext ( )

Determines if an event can be pulled from the output, by trying "harder" than hasNextSoft().

Depending on what happens, the possible return values are:

If one of the inputs answers "no" when called for hasNextSoft(), returns "no"
If all inputs answer "yes" when called for hasNextSoft(), and an event is produced with the given inputs, returns "yes"
Otherwise, the method will keep calling hasNext() on the inputs as long as they don't answer "no", and will try to produce an output event until one is produced.
To avoid infinite looping, the method eventually gives up (and answers "no") after some maximum number of repetitions is reached. This is configured by the static field Processor#MAX_PULL_RETRIES.

Returns: Whether a next event exists

◆ hasNextSoft()

NextStatus ca.uqac.lif.cep.Pullable.hasNextSoft ( )

Determines if an event can be pulled from the output.

Depending on what happens, the possible return values are:

If one of the inputs answers "no" when called for hasNextSoft(), returns "no"
If one of the inputs answers "maybe" when called for hasNextSoft(), returns "maybe"
If all inputs answer "yes" when called for hasNextSoft(), but no event is produced with the given inputs, returns "maybe"
Otherwise, returns "yes"

Therefore, the method is lazy in that it asks events from its input only once, and attempts to produce an output event only once.

Returns: Whether a next event exists

Implemented in ca.uqac.lif.cep.AsynchronousProcessor.OutputPullable, ca.uqac.lif.cep.functions.ApplyFunctionPartial.OutputPullable, ca.uqac.lif.cep.GroupProcessor.ProxyPullable, ca.uqac.lif.cep.Pullable.PullNotSupported, ca.uqac.lif.cep.SynchronousProcessor.OutputPullable, ca.uqac.lif.cep.tmf.Divert.DivertPullable, ca.uqac.lif.cep.tmf.Multiplex.MuxPullable, ca.uqac.lif.cep.tmf.Tank.QueuePullable, ca.uqac.lif.cep.TypedPullable< T >, and ca.uqac.lif.cep.UniformProcessor.UnaryPullable.

◆ next()

Object ca.uqac.lif.cep.Pullable.next ( )

Attempts to obtain an event from the source.

An event is returned if hasNext() returns YES, and java.util.NoSuchElementException is thrown otherwise.

Returns: An event

Exceptions

java.util.NoSuchElementException if the iteration has no more elements

Implemented in ca.uqac.lif.cep.AsynchronousProcessor.OutputPullable, ca.uqac.lif.cep.functions.ApplyFunctionPartial.OutputPullable, ca.uqac.lif.cep.GroupProcessor.ProxyPullable, ca.uqac.lif.cep.Pullable.PullNotSupported, ca.uqac.lif.cep.SynchronousProcessor.OutputPullable, ca.uqac.lif.cep.tmf.Divert.DivertPullable, ca.uqac.lif.cep.tmf.Multiplex.MuxPullable, ca.uqac.lif.cep.tmf.Tank.QueuePullable, ca.uqac.lif.cep.TypedPullable< T >, and ca.uqac.lif.cep.UniformProcessor.UnaryPullable.

◆ pull()

Object ca.uqac.lif.cep.Pullable.pull ( )

Attempts to pull an event from the source.

An event is returned if hasNext() returns YES, and java.util.NoSuchElementException is thrown otherwise.

Returns: An event

Exceptions

java.util.NoSuchElementException if the iteration has no more elements

Implemented in ca.uqac.lif.cep.AsynchronousProcessor.OutputPullable, ca.uqac.lif.cep.functions.ApplyFunctionPartial.OutputPullable, ca.uqac.lif.cep.GroupProcessor.ProxyPullable, ca.uqac.lif.cep.Pullable.PullNotSupported, ca.uqac.lif.cep.SynchronousProcessor.OutputPullable, ca.uqac.lif.cep.tmf.Divert.DivertPullable, ca.uqac.lif.cep.tmf.Multiplex.MuxPullable, ca.uqac.lif.cep.tmf.Tank.QueuePullable, ca.uqac.lif.cep.TypedPullable< T >, and ca.uqac.lif.cep.UniformProcessor.UnaryPullable.

◆ pullSoft()

Object ca.uqac.lif.cep.Pullable.pullSoft ( )

Attempts to pull an event from the source.

An event is returned if hasNextSoft() returns YES, and null is returned otherwise.

Returns: An event, or null if none could be retrieved

Implemented in ca.uqac.lif.cep.AsynchronousProcessor.OutputPullable, ca.uqac.lif.cep.functions.ApplyFunctionPartial.OutputPullable, ca.uqac.lif.cep.GroupProcessor.ProxyPullable, ca.uqac.lif.cep.Pullable.PullNotSupported, ca.uqac.lif.cep.SynchronousProcessor.OutputPullable, ca.uqac.lif.cep.tmf.Divert.DivertPullable, ca.uqac.lif.cep.tmf.Multiplex.MuxPullable, ca.uqac.lif.cep.tmf.Tank.QueuePullable, ca.uqac.lif.cep.TypedPullable< T >, and ca.uqac.lif.cep.UniformProcessor.UnaryPullable.

◆ start()

void ca.uqac.lif.cep.Pullable.start ( )

Starts the pullable.

This may be useful for multi-threaded pullables.

Implemented in ca.uqac.lif.cep.AsynchronousProcessor.OutputPullable, ca.uqac.lif.cep.functions.ApplyFunctionPartial.OutputPullable, ca.uqac.lif.cep.GroupProcessor.ProxyPullable, ca.uqac.lif.cep.Pullable.PullNotSupported, ca.uqac.lif.cep.SynchronousProcessor.OutputPullable, ca.uqac.lif.cep.tmf.Divert.DivertPullable, ca.uqac.lif.cep.tmf.Multiplex.MuxPullable, ca.uqac.lif.cep.tmf.Tank.QueuePullable, ca.uqac.lif.cep.TypedPullable< T >, and ca.uqac.lif.cep.UniformProcessor.UnaryPullable.

◆ stop()

void ca.uqac.lif.cep.Pullable.stop ( )

Stops the pullable.

This may be useful for multi-threaded pullables.

Implemented in ca.uqac.lif.cep.AsynchronousProcessor.OutputPullable, ca.uqac.lif.cep.functions.ApplyFunctionPartial.OutputPullable, ca.uqac.lif.cep.GroupProcessor.ProxyPullable, ca.uqac.lif.cep.Pullable.PullNotSupported, ca.uqac.lif.cep.SynchronousProcessor.OutputPullable, ca.uqac.lif.cep.tmf.Divert.DivertPullable, ca.uqac.lif.cep.tmf.Multiplex.MuxPullable, ca.uqac.lif.cep.tmf.Tank.QueuePullable, ca.uqac.lif.cep.TypedPullable< T >, and ca.uqac.lif.cep.UniformProcessor.UnaryPullable.

The documentation for this interface was generated from the following file:

/home/sylvain/Workspaces/beepbeep/core/src/ca/uqac/lif/cep/Pullable.java

Detailed Description

Classes

Public Member Functions

Member Function Documentation

◆ dispose()

◆ getPosition()

◆ getProcessor()

◆ hasNext()

◆ hasNextSoft()

◆ next()

◆ pull()

◆ pullSoft()

◆ start()

◆ stop()