<commit_before><h3>Derived State</h3>

<p>
  One of the core goals of ember-concurrency is to provide as much
  <strong>Derived State</strong> as possible; for example, instead
  of requiring you to set and then later unset your own <code>isRunning</code>
  flag at the beginning and end of a task, ember-concurrency gives you
  an <code>.isRunning</code> (and <code>.isIdle</code>) property for free so that
  you don't have to manage your own state (which is a common source of bugs
  and boilerplate).
</p>

<p>
  ember-concurrency gives you the concept of <strong>Tasks</strong>, and
  when you <code>perform</code> a Task, it produces a
  <strong>Task Instance</strong>, which represents a single execution
  of that task. Both of these objects expose a lot of derived state,
  which is described below.
</p>

<p>
  Less commonly-used properties are <em>italicized</em>. Also, keep in
  mind that there are <a href="/api">API docs</a> for everything described below.
</p>

<h4>Properties on <a href="/api/Task.html">Task</a> objects</h4>

<ul>
  <li>
    <code>isRunning</code>:
    true when there is at least one instance of the task running, false otherwise.
  </li>
  <li>
    <code>isIdle</code>: the opposite of <code>isRunning</code>
  </li>
  <li>
    <em><code>performCount</code></em>: The number of times the task has been performed
  </li>
  <li>
    <em><code>concurrency</code></em>: an integer representing the number of currently
    running task instances. If you're using a task modifier like
    <code>drop/enqueue/restartable</code> (without specifying <code>maxConcurrency</code>)
    this number will never be greater than 1. This property is mostly useful for
    debugging.
  </li>
  <li>
    <em><code>state</code></em>: a string description of the task's state; can
    either by "running" or "idle". Useful for debugging.
  </li>
</ul>

<h5>Accessing Task Instances from the Task object</h5>

<p>
  Tasks also expose properties for accessing specific
  Task Instances (which are created every time you call <code>.perform()</code>
  on a task).
</p>

<ul>
  <li>
    <code>last</code>: the last Task Instance that started executing.
    This property will never point to a <code>drop</code>ped Task Instance,
  </li>
  <li>
    <code>lastSuccessful</code>: the last Task Instance that ran to completion
    (it returned a value that wasn't a rejecting promise).
  </li>
  <li>
    <code>isSuccessful</code>: true if the Task Instance ran to completion
  </li>
  <li>
    <code>isError</code>: true if Task Instance failed to run to completion due to an exception
  </li>
</ul>

<p>
  In addition to these properties, keep in mind that at any point you can
  also just save the TaskInstance returned from <code>.perform()</code>
  to some property for later access in case the above properties don't
  hit your use cases (but please open a GitHub issue if you find yourself
  doing this often because this might suggest room for improvement in
  ember-concurrency's API).
</p>

<h4>Properties on <a href="/api/TaskInstance.html">Task Instances</a></h4>

<ul>
  <li>
    <code>value</code>: the value returned from the task function. Is
    <code>null</code> before a value is returned, and remains null
    if the task never completes (throws an error or is canceled).
  </li>

  <li>
    <code>error</code>: the error/exception thrown from the task function
    (might also be the value of a rejected promise that was yielded).
    <em>Note: until <a href="https://github.com/machty/ember-concurrency/issues/40">this issue</a>
      is resolved, unless you write code to explicitly <code>.catch()</code>
      an error thrown from a performed task, this error will bubble
      to the browser (so error reporters like Bugsnag will see it).
    </em>
  </li>
</ul>

<h4>Put the two together...</h4>

<p>
  Given a task named <code>myTask</code>, if you need to display a success banner
  with the value returned from the most recent execution of <code>myTask</code>,
  you can simply reference <code>\{{myTask.last.value}}</code>. If want this banner
  to persist until the next time the task runs to completion, you can
  just change it to <code>\{{myTask.lastSuccessful.value}}</code>. There are other
  combinations as well that might better suit your UI needs.
</p>

<h3>Live Example</h3>

<p>
  {{input type="checkbox" checked=showLessCommon}} Show less common properties
</p>

{{#each tasks as |taskName|}}
  {{#with (get this taskName) as |task|}}
    <h5>{{task.name}} (performCount={{task.performCount}} concurrency={{task.concurrency}})</h5>

    <p>
      <button onclick={{perform task false}}
        class={{if task.isIdle 'button-primary'}}>
        Run to Completion
      </button>
      <button onclick={{perform task true}}
        class={{if task.isIdle 'button-primary'}}>
        Run until Error
      </button>
      <button onclick={{cancel-all task}}
        class={{if task.isRunning 'button-primary'}}>
        Cancel
      </button>
    </p>

    <table class="u-full-width completion-state-table">
      <thead>
        <tr>
          <th>Completion Property</th>
          <th>.value</th>
          <th>.error</th>
          <th>.isSuccessful</th>
          <th>.isError</th>
        </tr>
      </thead>
      <tbody>
        {{#each taskProperties as |tp|}}
        <tr>
          <td>
            <strong>myTask.{{tp}}</strong>
          </td>
          <td>
            {{#with (get task (concat tp '.value')) as |v|}}
              <div class="completion-status completion-success">{{v}}</div>
            {{/with}}
          </td>
          <td>
            {{#with (get task (concat tp '.error')) as |v|}}
              <div class="completion-status completion-error">{{v}}</div>
            {{/with}}
          </td>
          <td>
            {{#with (get task (concat tp '.isSuccessful')) as |v|}}
              {{v}}
            {{/with}}
          </td>
          <td>
            {{#with (get task (concat tp '.isError')) as |v|}}
              {{v}}
            {{/with}}
          </td>
        </tr>
        {{/each}}
      </tbody>
    </table>
    <br />
  {{/with}}
{{/each}}

<commit_msg>Fix task vs task instance properties (#236)<commit_after><h3>Derived State</h3>

<p>
  One of the core goals of ember-concurrency is to provide as much
  <strong>Derived State</strong> as possible; for example, instead
  of requiring you to set and then later unset your own <code>isRunning</code>
  flag at the beginning and end of a task, ember-concurrency gives you
  an <code>.isRunning</code> (and <code>.isIdle</code>) property for free so that
  you don't have to manage your own state (which is a common source of bugs
  and boilerplate).
</p>

<p>
  ember-concurrency gives you the concept of <strong>Tasks</strong>, and
  when you <code>perform</code> a Task, it produces a
  <strong>Task Instance</strong>, which represents a single execution
  of that task. Both of these objects expose a lot of derived state,
  which is described below.
</p>

<p>
  Less commonly-used properties are <em>italicized</em>. Also, keep in
  mind that there are <a href="/api">API docs</a> for everything described below.
</p>

<h4>Properties on <a href="/api/Task.html">Task</a> objects</h4>

<ul>
  <li>
    <code>isRunning</code>:
    true when there is at least one instance of the task running, false otherwise.
  </li>
  <li>
    <code>isIdle</code>: the opposite of <code>isRunning</code>
  </li>
  <li>
    <em><code>performCount</code></em>: The number of times the task has been performed
  </li>
  <li>
    <em><code>concurrency</code></em>: an integer representing the number of currently
    running task instances. If you're using a task modifier like
    <code>drop/enqueue/restartable</code> (without specifying <code>maxConcurrency</code>)
    this number will never be greater than 1. This property is mostly useful for
    debugging.
  </li>
  <li>
    <em><code>state</code></em>: a string description of the task's state; can
    either by "running" or "idle". Useful for debugging.
  </li>
</ul>

<h5>Accessing Task Instances from the Task object</h5>

<p>
  Tasks also expose properties for accessing specific
  Task Instances (which are created every time you call <code>.perform()</code>
  on a task).
</p>

<ul>
  <li>
    <code>last</code>: the last Task Instance that started executing.
    This property will never point to a <code>drop</code>ped Task Instance,
  </li>
  <li>
    <code>lastSuccessful</code>: the last Task Instance that ran to completion
    (it returned a value that wasn't a rejecting promise).
  </li>
</ul>

<p>
  In addition to these properties, keep in mind that at any point you can
  also just save the TaskInstance returned from <code>.perform()</code>
  to some property for later access in case the above properties don't
  hit your use cases (but please open a GitHub issue if you find yourself
  doing this often because this might suggest room for improvement in
  ember-concurrency's API).
</p>

<h4>Properties on <a href="/api/TaskInstance.html">Task Instances</a></h4>

<ul>
  <li>
    <code>isSuccessful</code>: true if the Task Instance ran to completion
  </li>
  
  <li>
    <code>isError</code>: true if Task Instance failed to run to completion due to an exception
  </li>
  
  <li>
    <code>value</code>: the value returned from the task function. Is
    <code>null</code> before a value is returned, and remains null
    if the task never completes (throws an error or is canceled).
  </li>

  <li>
    <code>error</code>: the error/exception thrown from the task function
    (might also be the value of a rejected promise that was yielded).
    <em>Note: until <a href="https://github.com/machty/ember-concurrency/issues/40">this issue</a>
      is resolved, unless you write code to explicitly <code>.catch()</code>
      an error thrown from a performed task, this error will bubble
      to the browser (so error reporters like Bugsnag will see it).
    </em>
  </li>
</ul>

<h4>Put the two together...</h4>

<p>
  Given a task named <code>myTask</code>, if you need to display a success banner
  with the value returned from the most recent execution of <code>myTask</code>,
  you can simply reference <code>\{{myTask.last.value}}</code>. If want this banner
  to persist until the next time the task runs to completion, you can
  just change it to <code>\{{myTask.lastSuccessful.value}}</code>. There are other
  combinations as well that might better suit your UI needs.
</p>

<h3>Live Example</h3>

<p>
  {{input type="checkbox" checked=showLessCommon}} Show less common properties
</p>

{{#each tasks as |taskName|}}
  {{#with (get this taskName) as |task|}}
    <h5>{{task.name}} (performCount={{task.performCount}} concurrency={{task.concurrency}})</h5>

    <p>
      <button onclick={{perform task false}}
        class={{if task.isIdle 'button-primary'}}>
        Run to Completion
      </button>
      <button onclick={{perform task true}}
        class={{if task.isIdle 'button-primary'}}>
        Run until Error
      </button>
      <button onclick={{cancel-all task}}
        class={{if task.isRunning 'button-primary'}}>
        Cancel
      </button>
    </p>

    <table class="u-full-width completion-state-table">
      <thead>
        <tr>
          <th>Completion Property</th>
          <th>.value</th>
          <th>.error</th>
          <th>.isSuccessful</th>
          <th>.isError</th>
        </tr>
      </thead>
      <tbody>
        {{#each taskProperties as |tp|}}
        <tr>
          <td>
            <strong>myTask.{{tp}}</strong>
          </td>
          <td>
            {{#with (get task (concat tp '.value')) as |v|}}
              <div class="completion-status completion-success">{{v}}</div>
            {{/with}}
          </td>
          <td>
            {{#with (get task (concat tp '.error')) as |v|}}
              <div class="completion-status completion-error">{{v}}</div>
            {{/with}}
          </td>
          <td>
            {{#with (get task (concat tp '.isSuccessful')) as |v|}}
              {{v}}
            {{/with}}
          </td>
          <td>
            {{#with (get task (concat tp '.isError')) as |v|}}
              {{v}}
            {{/with}}
          </td>
        </tr>
        {{/each}}
      </tbody>
    </table>
    <br />
  {{/with}}
{{/each}}


{'fraction_non_alphanumeric': 0.13294003555842895, 'fraction_numerical': 0.00299014061742363, 'mean_word_length': 2.7995087503837888, 'pattern_counts': {'":': 0, '<': 361, '<?xml version=': 0, '>': 361, 'https://': 2, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5209510', 'n_tokens_mistral': 3796, 'n_tokens_neox': 3740, 'n_words': 1410}