1// Copyright 2017 The Fuchsia Authors. All rights reserved.
2// Use of this source code is governed by a BSD-style license that can be
3// found in the LICENSE file.
4
5#pragma once
6
7#include <zircon/compiler.h>
8#include <zircon/types.h>
9
10__BEGIN_CDECLS
11
12// Called on a task (job/process/thread) node by walk_job_tree().
13//
14// context: The same value passed to walk_[root_]job_tree(), letting callers pass
15//     a context (e.g., object or struct) into each callback of a walk.
16// depth: The distance from root_job. root_job has depth 0, direct
17//     children have depth 1, and so on.
18// task: A handle to the job/process/thread. Will be closed automatically
19//     after the callback returns, so callers should duplicate the handle
20//     if they want to use it later.
21// koid: The koid of the task that the handle points to.
22// parent_koid: The koid of the parent task (e.g., the process the contains the
23//     thread, the job that contains the process, or the job that contains the
24//     job).
25//
26// If the callback returns a value other than ZX_OK, the job tree walk will
27// terminate without visiting any other node, and the zx_status_t value will be
28// returned by walk_job_tree().
29typedef zx_status_t(task_callback_t)(
30    void* context, int depth,
31    zx_handle_t task, zx_koid_t koid, zx_koid_t parent_koid);
32
33// Walks the job/process/task tree rooted in root_job. Visits tasks in
34// depth-first pre order. Any callback arg may be NULL.
35// |context| is passed to all callbacks.
36zx_status_t walk_job_tree(zx_handle_t root_job,
37                          task_callback_t job_callback,
38                          task_callback_t process_callback,
39                          task_callback_t thread_callback,
40                          void* context);
41
42// Calls walk_job_tree() on the system's root job. Will fail if the calling
43// process does not have the rights to access the root job.
44// TODO(dbort): Add a different lib/API to get the system root job and remove
45// this function.
46zx_status_t walk_root_job_tree(task_callback_t job_callback,
47                               task_callback_t process_callback,
48                               task_callback_t thread_callback,
49                               void* context);
50
51__END_CDECLS
52
53// C++ interface
54#ifdef __cplusplus
55// Interface for walking a job tree.
56class TaskEnumerator {
57public:
58    // Each of these methods visits the corresponding task type. If any On*()
59    // method returns a value other than ZX_OK, the enumeration stops. See
60    // |task_callback_t| for a description of parameters.
61    virtual zx_status_t OnJob(
62        int depth, zx_handle_t job, zx_koid_t koid, zx_koid_t parent_koid) {
63        return ZX_ERR_NOT_SUPPORTED;
64    }
65    virtual zx_status_t OnProcess(
66        int depth, zx_handle_t process, zx_koid_t koid, zx_koid_t parent_koid) {
67        return ZX_ERR_NOT_SUPPORTED;
68    }
69    virtual zx_status_t OnThread(
70        int depth, zx_handle_t process, zx_koid_t koid, zx_koid_t parent_koid) {
71        return ZX_ERR_NOT_SUPPORTED;
72    }
73
74    // Walks the job/process/task tree rooted in root_job. Visits tasks in
75    // depth-first pre order.
76    zx_status_t WalkJobTree(zx_handle_t root_job);
77
78    // Calls WalkJobTree() on the system's root job. Will fail if the calling
79    // process does not have the rights to access the root job.
80    // TODO(dbort): Add a different lib/API to get the system root job and
81    // remove this function.
82    zx_status_t WalkRootJobTree();
83
84protected:
85    TaskEnumerator() = default;
86    virtual ~TaskEnumerator() = default;
87
88    // Subclasses must overload these to indicate which task types to actually
89    // visit. Avoids, e.g., visiting every thread in the system when a caller
90    // only cares about jobs.
91    virtual bool has_on_job() const { return false; }
92    virtual bool has_on_process() const { return false; }
93    virtual bool has_on_thread() const { return false; }
94};
95#endif // __cplusplus
96