Debian Codegraph @

libdrgn/lazy_object.h

raw
1 // Copyright (c) Meta Platforms, Inc. and affiliates.
2 // SPDX-License-Identifier: LGPL-2.1-or-later
3
4 /**
5 * @file
6 *
7 * Lazy objects.
8 *
9 * See @ref LazyObjects.
10 */
11
12 #ifndef DRGN_LAZY_OBJECT_H
13 #define DRGN_LAZY_OBJECT_H
14
15 #include "drgn_internal.h"
16
17 /**
18 * @ingroup Internals
19 *
20 * @defgroup LazyObjects Lazy objects
21 *
22 * Lazily-evaluated objects.
23 *
24 * The graph of objects and types in a program can be very deep (and often
25 * cyclical), so drgn lazily evaluates objects in some cases.
26 *
27 * @{
28 */
29
30 /**
31 * Initialize an unevaluated @ref drgn_lazy_object.
32 *
33 * @param[out] lazy_obj Lazy object to initialize.
34 * @param[in] prog Program owning the lazy object.
35 * @param[in] fn Thunk callback.
36 * @param[in] arg Argument to pass to @p fn.
37 */
38 static inline void
39 drgn_lazy_object_init_thunk(union drgn_lazy_object *lazy_obj,
40 struct drgn_program *prog, drgn_object_thunk_fn *fn,
41 void *arg)
42 {
43 lazy_obj->thunk.dummy_type = NULL;
44 lazy_obj->thunk.prog = prog;
45 lazy_obj->thunk.fn = fn;
46 lazy_obj->thunk.arg = arg;
47 }
48
49 /** Return whether a @ref drgn_lazy_object has been evaluated. */
50 static inline bool
51 drgn_lazy_object_is_evaluated(const union drgn_lazy_object *lazy_obj)
52 {
53 return lazy_obj->obj.type != NULL;
54 }
55
56 /**
57 * Evaluate a @ref drgn_lazy_object.
58 *
59 * If this success, then the lazy object is considered evaluated and future
60 * calls will always succeed. If this fails, then the lazy object remains in a
61 * valid, unevaluated state.
62 */
63 struct drgn_error *drgn_lazy_object_evaluate(union drgn_lazy_object *lazy_obj);
64
65 /**
66 * Free a @ref drgn_lazy_object.
67 *
68 * If the object has been evaluated, then this deinitializes @ref
69 * drgn_lazy_object::obj. Otherwise, this calls @ref drgn_lazy_object::fn to
70 * free @ref drgn_lazy_object::arg.
71 */
72 void drgn_lazy_object_deinit(union drgn_lazy_object *lazy_obj);
73
74 /**
75 * Check whether a @ref drgn_lazy_object belongs to a given @ref drgn_program.
76 *
77 * @return @c NULL if the program matches, non-@c NULL if not.
78 */
79 struct drgn_error *
80 drgn_lazy_object_check_prog(const union drgn_lazy_object *lazy_obj,
81 struct drgn_program *prog);
82
83 /** @} */
84
85 #endif /* DRGN_LAZY_OBJECT_H */