# Triead reference

The Triead class is the public interface of a Triceps thread, i.e. what of it is visible to the other threads. It's intended pretty much for introspection only, and all its method are only for reading the state. They are all synchronized, but of course the thread may change its state at any moment. The Triead objects can be obtained by calling

    App::getTrieads()

.

The class also contains some static methods that are used to construct the Trieads.

    $result = $t->same($t2);

Check that two Triead references point to the same Triead object.

    $name = $t->getName();

Get the Triead's name.

    $fragment = $t->fragment();

Get the name of the Triead's fragment. If the Triead doesn't belong to a fragment, returns an empty string .

    $result = $t->isConstructed();

Check whether the Triead has been constructed. For the explanation of the Triead lifecycle states, see &xrsp;.

    $result = $t->isReady();

Check whether the Triead is ready.

    $result = $t->isDead();

Check whether the Triead is dead.

    $result = $t->isInputOnly();

Check whether the Triead is input-only, that is, it has no reader nexuses imported into it. When the Triead is created, this flag starts its life as

    false

(0 for Perl), and then its correct value is computed when the Triead becomes ready. So, to check this flag correctly, you must first check that the Triead is ready.

    @nexuses = $t->exports();

Get the list of nexuses exported from this Triead, as name-value pairs, suitable to be assigned into a hash. The values are the references to nexus objects.

    @nexuses = $t->imports();
    @nexuses = $t->readerImports();
    @nexuses = $t->writerImports();

Get the list of nexuses imported into this Triead, as name-value pairs. The

    imports()

returns the full list, without the ability to tell, which nexuses are imported for reading and which for writing, while

    readImports()

and

    writeImports()

return these subsets separately.

The names here are the as-names used for the import (the full names of the Nexuses can be obtained from the Nexus objects). The values are the references to nexus objects.

The next part of the API is the static construction methods. They really are wrappers of the TrieadOwner methods but Triead is a shorter name, and thus more convenient.

    Triceps::Triead::start(@options);

Start a new Triead in a new Perl thread. The options are:

    app => $appname

  Name of the App that owns the new Triead. The App object will be looked up by name for the actual construction.

    thread => $threadname

  Name of the new Triead.

    fragment => $fragname

  Name of the new Triead's fragment. Optional. Default: , which means no fragment.

    immed => 0/1

  Flag: when the new thread imports its nexuses, it should import them in the immediate mode. This flag is purely advisory, and the thread's main function is free to use or ignore it depending on its logic. It's provided as a convenience, since it's a typical concern for the helper threads. Optional. Default: 0.

    main => $code

  The main function of the thread that will be called with all the options of

      start()

  plus some more:

      &$func(@opts, owner => $ownerObj)

  The extra option of the main is:

      owner => $ownerObj

    The TrieadOwner object constructed for this thread, through which its state can be controlled.

  Also, any other options may be added, and they will be forwarded to the main function without parsing. The main function is then free to parse them by itself, and if it finds any unknown options, it will fail.

  For the convenience of writing the main functions, the set of standard options is provided in the global variable

      @Triceps::Triead::opts

  The main function then uses this variable as a preamble for any of its own options, for example:

      sub listenerT
      {
          my $opts = {};
          &Triceps::Opt::parse("listenerT", $opts, {@Triceps::Triead::opts,
              socketName => [ undef, \&Triceps::Opt::ck_mandatory ],
          }, @_);
          ...
      }

Another convenience method is:

    Triceps::Triead::startHere(@options);

It's very much the same as

    start()

but starts the Triead in the current Perl thread. It's intended for the short-lived Apps that perform some computation and then have to return the result into the original thread. The unit tests are a good example of such apps.

And because of the typical usage, this method has some extra functionality compared to the plain

    start()

: unless told otherwise, it will first create the App (with the name specified by the option app), then construct and run it, and after the main function of this thread exits, run the harvester and drop the App. So it just does the whole package, similar to

    App::build()

, only typically the Triead started here runs as a normal real Triead, collects the results of computations and places them into some variables (global or referenced by the user-specific options of the main function).

This extra functionality can be disabled by the additional options (disable by setting them to 0):

    harvest => 0/1

  After the main function exits, automatically run the harvesrer. If you set it to 0, don't forget to call the harvester after this function returns. Optional. Default: 1.

    makeApp => 0/1

  Before doing anything, create the App. Obviously, this App must not exist yet. Optional. Default: 1.

These options are not passed through to the main function, unlike all the others.

Triead