# FnReturn reference

The FnReturn represents the return value of a streaming function. The return value consists of a stream of rowops, and gets processed by sending them to the labels through a binding.

    $fret = Triceps::FnReturn->new($optName => $optValue, ...);

Construct an FnReturn object. The options are:

    name => $name

  Name of this object. Will be used to create the names of the labels in it.

    unit => $unit

  The unit where this object belongs.

    labels => [ @definitions ]

  Definition of the labels in the FnReturn, where the results of the streaming function will be sent. The full names of these labels will be return_name.label_name. The label names within a return must be unique. The value for this option is an array reference, with the labels defined as name-value pairs in the array, in one of two forms:

      labels => [
      	$name1 => $rowType1,
      	$name2 => $fromLabel2,
      	...
      ]

  If the second element in the pair is a row type, a label of that row type will be created in the FnReturn.

  If the second element in the pair is a label, its row type will be used to create a label in FnReturn and that new label will also be automatically chained off the specified one. This is convenient if you already have the logic of the function defined and just want to forward the result data from an existing label into the FnReturn. The chaining is normally done with

      chainFront()

  , unless the option

      chainFront => 0

  tells otherwise. The front chaining is convenient if you want to pass both the original request and the result into the return. Usually you would define the result computation and then define the return. With the chaining at the back, this would lead to the computation chained off the input label first and the return going after it. This would lead to the result coming out before the argument, and special contortions would be needed to avoid it. With chaining at the front, the return will go in the chain before the computation, even if the return was defined last.

    chainFront => 0/1

  Flag: Determines whether the FnReturn labels built by chaining off the other labels will be chained at the back (if 0) or at the front (if 1). Optional. Default: 1.

    onPush => $code

  The code to execute whenever an FnBinding is pushed onto this FnReturn. This is useful to maintain the extended call contexts for the streaming function. Its argument can be specified in one of two forms: either just a code reference, or a reference to an array containing the code reference and the extra arguments for it. I.e. either

      onPush => $code

  or

      onPush => [ $code, @args ]

  . The first argument of the function will always be the FnReturn object itself, with extra arguments going after it:

      &$code($thisFnReturn, @optional_args)

  . As usual, a source code string may be used instead of the function reference. Optional.

    onPop => $code

  The code to execute whenever an FnBinding is popped from this FnReturn. This is useful to maintain the extended call contexts for the streaming function. Its argument can be specified in one of two forms: either just a code reference, or a reference to an array containing the code reference and the extra arguments for it. I.e. either

      onPop => $code

  or

      onPop => [ $code, @args ]

  . The first argument of the function will always be the FnReturn object itself, with extra arguments going after it:

      &$code($thisFnReturn, @optional_args)

  . As usual, a source code string may be used instead of the function reference. Optional.

The FnReturn has a concept of clearing: and once any of the labels owned by the FnReturn gets cleared, the FnReturn is also cleared. The clearing drops the onPush and onPop handlers, thus breaking any reference cycles they might be engaged in.

Also, when an FnReturn gets destroyed, it clears and disconnects from the Unit all the labels defined in that FnReturn. The reason for that is that the labels in FnReturn cannot work without the FnReturn object anyway, and cannot hold a reference to it either (to avoid the cyclical references).

    $name = $fret->getName();

Get back the object's name.

    $res = $fret->size();

Get the number of labels in the return.

    @names = $fret->getLabelNames();

Get an array of label names, in the same order as they were defined (the order of the label definitions is important).

    @labels = $fret->getLabels();

Get an array of references to the FnReturn's internal labels, in the same order as they were defined.

    %labels = $fret->getLabelHash();

Get the interspersed list of label names and references, suitable to initialize a hash.

    %namemap = $fret->getLabelMapping();

Get the interspersed list of label names and their indexes in order starting from 0, suitable to initialize a hash.

    $label = $fret->getLabel($name);

Get a label by name. Will confess if this name was not defined.

    $label = $fret->getLabelAt($idx);

Get a label by index, starting from 0. Will confess if the index is out of range.

    $idx = $fret->findLabel($name);

Translate a label name to index. Will confess if this name was not defined.

    %rts = $fret->getRowTypeHash();

Get the interspersed list of label names and references to their row types, suitable to initialize a hash. In Perl, this is the closest thing to the &Cpp; API's RowSetType.

    $res = $fret->equals($fret2);
    $res = $fret->equals($fbind2);
    $res = $fret->match($fret2);
    $res = $fret->match($fbind2);

Compare the equality or match of types with an FnReturn or FnBinding. Since their type objects are not directly visible in the Perl API, the comparison has to be done on the FnReturns and FnBindings themselves. The types are considered equal if they contain the equal row types with equal names going in the same order. They are considered matching if they contain matching row types going in the same order, with any names. If the match condition seems surprising to you, think of it as nothing will break if one type is substituted for another at execution time.

    $res = $fret->same($fret2);

The usual check for two references referring to the same FnReturn object.

    $fret->push($fbind);

Push a binding on the return stack. The binding must be of a matching type. The reference to the binding will be kept in the FnReturn until it's popped.

    $fret->pop($fbind);
    $fret->pop();

Pop a binding from the return stack. The binding argument specifies, which binding is expected to be popped. Without argument, pops any binding. The call with argument is recommended since it allows to catch any mess-ups with the return stack early. If the stack is empty or the top binding is not the same as the argument, will confess.

    $res = $fret->bindingStackSize();

Get the current size of the return stack (AKA the stack of bindings). Useful for debugging.

    @names = $fret->bindingStackNames();

Get the names of all the bindings on the return stack. Useful for debugging. The top of stack is on the right.

    $res = fret->isFaceted();

Returns 1 if this FnReturn object is a part of a Facet.

FnReturn
Facet