#!/bin/bash
# StarPU --- Runtime system for heterogeneous multicore architectures.
#
# Copyright (C) 2012-2020  Université de Bordeaux, CNRS (LaBRI UMR 5800), Inria
#
# StarPU is free software; you can redistribute it and/or modify
# it under the terms of the GNU Lesser General Public License as published by
# the Free Software Foundation; either version 2.1 of the License, or (at
# your option) any later version.
#
# StarPU is distributed in the hope that it will be useful, but
# WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
#
# See the GNU Lesser General Public License in COPYING.LGPL for more details.
#
handle.refcnt usage
===================

It is the counter for a software rwlock, accounting the number of readers
(mode == STARPU_R) or writers (mode == STARPU_W)

It is thus used

- during task duration for each data
- right after completion of a data request
- during application data acquisition

* Creates a reference:
  * Released by _starpu_notify_data_dependencies():
    - _starpu_attempt_to_submit_data_request() immediately when returning 0, but otherwise (1) when the pending request is given control
  * Released by _starpu_notify_data_dependencies():
    - _starpu_notify_data_dependencies() when may_unlock_data_req_list_head returned a request which can proceed

* Indirectly creates a reference:
  * Released by starpu_data_release():
    - _starpu_attempt_to_submit_data_request_from_apps() when returning 0
    - starpu_data_acquire_cb()
    - starpu_data_acquire()
  * Released by _starpu_notify_data_dependencies():
    - attempt_to_submit_data_request_from_job() when returning 0
  * Released by _starpu_push_task_output():
    - _submit_job_enforce_data_deps() for each data.

* Releases a reference:
  - _starpu_notify_data_dependencies()

* Indirectly releases a reference:
  - _starpu_release_data_on_node()
  - _starpu_push_task_output() for each data
  - starpu_data_release()

* Temporarily creates a reference, released immediately:
  - _starpu_write_through_data() for needed write-throughs, released by wt_callback
  - _starpu_benchmark_ping_pong()
  - _starpu_data_unregister()
  - _starpu_prefetch_data_on_node_with_mode()
  - starpu_data_invalidate()

TODO: unclear conversion use