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