Rename lttng_condition_event_rule to lttng_condition_on_event
[lttng-tools.git] / src / common / fd-tracker / fd-tracker.h
CommitLineData
df038819 1/*
ab5be9fa 2 * Copyright (C) 2018 Jérémie Galarneau <jeremie.galarneau@efficios.com>
df038819 3 *
ab5be9fa 4 * SPDX-License-Identifier: GPL-2.0-only
df038819 5 *
df038819
JG
6 */
7
8#ifndef FD_TRACKER_H
9#define FD_TRACKER_H
10
f7c3ffd7 11#include <common/compat/directory-handle.h>
938bd422 12#include <common/macros.h>
df038819
JG
13#include <stdint.h>
14#include <sys/types.h>
15
16struct fs_handle;
17struct fd_tracker;
18
19/*
20 * Callback which returns a file descriptor to track through the fd
21 * tracker. This callback must not make use of the fd_tracker as a deadlock
22 * may occur.
23 *
24 * The int pointer argument is an output parameter that should be used to return
25 * the advertised number of file descriptors.
26 *
27 * Must return zero on success. Negative values should map to a UNIX error code.
28 */
29typedef int (*fd_open_cb)(void *, int *out_fds);
30
31/*
32 * Callback to allow the user to close a now-untracked file descriptor. This
33 * callback must not make use of the fd_tracker as a deadlock may occur.
34 *
35 * The callback can freely modify the in_fds argument as it is copied by the
36 * fd_tracker before being used. The fd tracker assumes in_fds to be closed by
37 * the time the callback returns.
38 *
39 * Must return zero on success. Negative values should map to a UNIX error code.
40 */
41typedef int (*fd_close_cb)(void *, int *in_fds);
42
43/*
44 * Set the maximal number of fds that the process should be allowed to open at
45 * any given time. This function must be called before any other of this
46 * interface.
f7c3ffd7
JG
47 *
48 * The unlinked_file_path is an absolute path (which does not need to exist)
49 * under which unlinked files will be stored for as long as a reference to them
50 * is held.
df038819 51 */
938bd422 52LTTNG_HIDDEN
f7c3ffd7
JG
53struct fd_tracker *fd_tracker_create(const char *unlinked_file_path,
54 unsigned int capacity);
df038819
JG
55
56/* Returns an error if file descriptors are leaked. */
938bd422 57LTTNG_HIDDEN
df038819
JG
58int fd_tracker_destroy(struct fd_tracker *tracker);
59
60/*
61 * Open a handle to a suspendable filesystem file descriptor.
62 *
63 * See OPEN(3) for an explanation of flags and mode. NULL is returned in case of
64 * error and errno is left untouched. Note that passing NULL as mode will result
65 * in open()'s default behaviour being used (using the process' umask).
66 *
67 * A fs_handle wraps a file descriptor created by OPEN(3). It is suspendable
68 * meaning that the underlying file may be closed at any time unless the
69 * handle is marked as being in-use (see fs_handle_get_fd() and
70 * fs_handle_put_fd()).
71 *
72 * If the tracker opted to close the underlying file descriptor, it will
73 * be restored to its last known state when it is obtained through
74 * the fs_handle's fs_handle_get_fd() method.
75 *
76 * Note that a suspendable file descriptor can be closed by the fd tracker at
77 * anytime when it is not in use. This means that the user should not rely on it
78 * being safe to unlink the file. Moreover, concurent modifications to the file
79 * (e.g. truncation) may react differently than if the file descriptor was kept
80 * open.
81 */
938bd422 82LTTNG_HIDDEN
df038819 83struct fs_handle *fd_tracker_open_fs_handle(struct fd_tracker *tracker,
f7c3ffd7 84 struct lttng_directory_handle *directory,
5c1f54d1
JG
85 const char *path,
86 int flags,
87 mode_t *mode);
df038819
JG
88
89/*
90 * Open a tracked unsuspendable file descriptor.
91 *
92 * This function allows the fd tracker to keep track of unsuspendable
93 * file descriptors. A callback, open, is passed to allow the tracker
94 * to atomically reserve an entry for a given count of new file descriptors,
95 * suspending file descriptors as needed, and invoke the provided callback
96 * without ever exceeding the tracker's capacity.
97 *
98 * fd_count indicates the count of file descriptors that will be opened and
99 * returned by the open callback. The storage location at out_fds is assumed
100 * to be large enough to hold 'fd_count * sizeof(int)'.
101 *
102 * Names may be provided to allow easier debugging of file descriptor
103 * exhaustions.
104 *
105 * The callback's return value is returned to the user. Additionally, two
106 * negative tracker-specific codes may be returned:
107 * - ENOMEM: allocation of a new entry failed,
108 * - EMFILE: too many unsuspendable fds are opened and the tracker can't
d49487dc 109 * accommodates the request for a new unsuspendable entry.
df038819 110 */
938bd422 111LTTNG_HIDDEN
df038819 112int fd_tracker_open_unsuspendable_fd(struct fd_tracker *tracker,
5c1f54d1
JG
113 int *out_fds,
114 const char **names,
115 unsigned int fd_count,
116 fd_open_cb open,
117 void *data);
df038819
JG
118
119/*
120 * Close a tracked unsuspendable file descriptor.
121 *
122 * This function allows the fd tracker to keep track of unsuspendable
123 * file descriptors. A callback, close, is passed to allow the tracker
124 * to atomically release a file descriptor entry.
125 *
126 * Returns 0 if the close callback returned success. Returns the value returned
127 * by the close callback if it is negative. Additionally, a tracker-specific
128 * code may be returned:
129 * - EINVAL: a file descriptor was unknown to the tracker
130 *
131 * Closed fds are set to -1 in the fds array which, in the event of an error,
132 * allows the user to know which file descriptors are no longer being tracked.
133 */
938bd422 134LTTNG_HIDDEN
df038819 135int fd_tracker_close_unsuspendable_fd(struct fd_tracker *tracker,
5c1f54d1
JG
136 int *fds,
137 unsigned int fd_count,
138 fd_close_cb close,
df038819
JG
139 void *data);
140
141/*
142 * Log the contents of the fd_tracker.
143 */
938bd422 144LTTNG_HIDDEN
df038819
JG
145void fd_tracker_log(struct fd_tracker *tracker);
146
147/*
148 * Marks the handle as the most recently used and marks the 'fd' as
149 * "in-use". This prevents the tracker from recycling the underlying
150 * file descriptor while it is actively being used by a thread.
151 *
152 * Don't forget that the tracker may be initiating an fd 'suspension'
153 * from another thread as the need to free an fd slot may arise from any
154 * thread within the daemon.
155 *
156 * Note that a restorable fd should never be held for longer than
157 * strictly necessary (e.g. the duration of a syscall()).
158 *
159 * Returns the fd on success, otherwise a negative value may be returned
160 * if the restoration of the fd failed.
161 */
938bd422 162LTTNG_HIDDEN
df038819
JG
163int fs_handle_get_fd(struct fs_handle *handle);
164
165/*
166 * Used by the application to signify that it is no longer using the
167 * underlying fd and that it may be suspended.
168 */
938bd422 169LTTNG_HIDDEN
df038819
JG
170void fs_handle_put_fd(struct fs_handle *handle);
171
9d16fc7f
JG
172/*
173 * Unlink the file associated to an fs_handle. Note that the unlink
174 * operation will not be performed immediately. It will only be performed
175 * once all references to the underlying file (through other fs_handle objects)
176 * have been released.
177 *
178 * However, note that the file will be renamed so as to provide the observable
179 * effect of an unlink(), that is removing a name from the filesystem.
180 *
181 * Returns 0 on success, otherwise a negative value will be returned
182 * if the operation failed.
183 */
938bd422 184LTTNG_HIDDEN
9d16fc7f
JG
185int fs_handle_unlink(struct fs_handle *handle);
186
df038819
JG
187/*
188 * Frees the handle and discards the underlying fd.
189 */
938bd422 190LTTNG_HIDDEN
df038819
JG
191int fs_handle_close(struct fs_handle *handle);
192
193#endif /* FD_TRACKER_H */
This page took 0.034414 seconds and 4 git commands to generate.