Apache Mesos
cgroups.hpp
Go to the documentation of this file.
1 // Licensed to the Apache Software Foundation (ASF) under one
2 // or more contributor license agreements. See the NOTICE file
3 // distributed with this work for additional information
4 // regarding copyright ownership. The ASF licenses this file
5 // to you under the Apache License, Version 2.0 (the
6 // "License"); you may not use this file except in compliance
7 // with the License. You may obtain a copy of the License at
8 //
9 // http://www.apache.org/licenses/LICENSE-2.0
10 //
11 // Unless required by applicable law or agreed to in writing, software
12 // distributed under the License is distributed on an "AS IS" BASIS,
13 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 // See the License for the specific language governing permissions and
15 // limitations under the License.
16 
17 #ifndef __CGROUPS_HPP__
18 #define __CGROUPS_HPP__
19 
20 #include <stdint.h>
21 #include <stdlib.h>
22 
23 #include <set>
24 #include <string>
25 #include <vector>
26 
27 #include <sys/types.h>
28 
29 #include <process/future.hpp>
30 #include <process/timeout.hpp>
31 
32 #include <stout/bytes.hpp>
33 #include <stout/duration.hpp>
34 #include <stout/hashmap.hpp>
35 #include <stout/nothing.hpp>
36 #include <stout/option.hpp>
37 #include <stout/try.hpp>
38 
39 namespace cgroups {
40 
41 // Freezing a cgroup may get stuck (see MESOS-1689 for details). To
42 // workaround, we may want to thaw the cgroup and retry freezing it.
43 // This is the suggested retry interval.
45 
46 
47 // Default number of assign attempts when moving threads to a cgroup.
48 const unsigned int THREAD_ASSIGN_RETRIES = 100;
49 
50 // We use the following notations throughout the cgroups code. The notations
51 // here are derived from the kernel documentation. More details can be found in
52 // <kernel-source>/Documentation/cgroups/cgroups.txt.
53 //
54 // Hierarchy - A hierarchy contains a set of cgroups arranged in a tree such
55 // that every task in the system is in exactly one of the cgroups
56 // in the hierarchy. One or more subsystems can be attached to a
57 // hierarchy.
58 // Subsystem - A subsystem (e.g. cpu, memory, cpuset, etc) in the kernel. Each
59 // subsystem can be attached to only one hierarchy.
60 // Cgroup - A cgroup is just a set of tasks with a set of controls for one
61 // or more subsystems.
62 // Control - A control file in a cgroup (e.g. tasks, cpu.shares).
63 
64 
65 // TODO(idownes): Rework all functions in this file to better support
66 // separately mounted subsystems.
67 
68 // Prepare a hierarchy which has the specified subsystem (and only that
69 // subsystem) mounted and also has the specified cgroup created. Returns the
70 // hierarchy. Checks are made to ensure that cgroups are supported and that
71 // nested cgroups can be created.
73  const std::string& baseHierarchy,
74  const std::string& subsystem,
75  const std::string& cgroup);
76 
77 
78 // Returns error if any of the following is true:
79 // (a) hierarchy is not mounted,
80 // (b) cgroup does not exist
81 // (c) control file does not exist.
83  const std::string& hierarchy,
84  const std::string& cgroup = "",
85  const std::string& control = "");
86 
87 
88 // Check whether cgroups module is enabled on the current machine.
89 // @return True if cgroups module is enabled.
90 // False if cgroups module is not available.
91 bool enabled();
92 
93 
94 // Return the currently active hierarchies.
95 // @return A set of active hierarchy paths (e.g., '/cgroup').
96 // Error if unexpected happens.
98 
99 
100 // Get an already mounted hierarchy that has 'subsystems' attached.
101 // This function will return an error if we are unable to find the
102 // hierarchies or if we are unable to find if the subsystems are
103 // mounted at a given hierarchy.
104 // @param subsystems Comma-separated subsystem names.
105 // @return Path to the hierarchy root, if a hierarchy with all the
106 // given subsystems mounted exists.
107 // None, if no such hierarchy exists.
108 // Error, if the operation fails.
109 Result<std::string> hierarchy(const std::string& subsystems);
110 
111 
112 // Check whether all the given subsystems are enabled on the current machine.
113 // @param subsystems Comma-separated subsystem names.
114 // @return True if all the given subsystems are enabled.
115 // False if any of the given subsystems is not enabled.
116 // Error if something unexpected happens.
117 Try<bool> enabled(const std::string& subsystems);
118 
119 
120 // Return true if any of the given subsystems is currently attached to a
121 // hierarchy.
122 // @param subsystems Comma-separated subsystem names.
123 // @return True if any of the given subsystems is being attached.
124 // False if non of the given subsystems is being attached.
125 // Error if something unexpected happens.
126 Try<bool> busy(const std::string& subsystems);
127 
128 
129 // Return the currently enabled subsystems.
130 // @return A set of enabled subsystem names if succeeds.
131 // Error if unexpected happens.
133 
134 
135 // Return a set of subsystems that are attached to a given hierarchy. An error
136 // will be returned if the given hierarchy is not currently mounted with a
137 // cgroups virtual file system. As a result, this function can be used to check
138 // whether a hierarchy is indeed a cgroups hierarchy root.
139 // @param hierarchy Path to the hierarchy root.
140 // @return A set of attached subsystem names.
141 // Error otherwise, (e.g., hierarchy does not exist or is not mounted).
142 Try<std::set<std::string>> subsystems(const std::string& hierarchy);
143 
144 
145 // Mount a cgroups hierarchy and attach the given subsystems to
146 // it. This function will return error if the path given for the
147 // hierarchy already exists. Also, the function will return error if
148 // a subsystem in the given subsystem list has already been attached
149 // to another hierarchy. On success, the cgroups virtual file system
150 // will be mounted with the proper subsystems attached. On failure,
151 // mount will be retried the specified number of times.
152 // @param hierarchy Path to the hierarchy root.
153 // @param subsystems Comma-separated subsystem names.
154 // @param retry Number of times to retry mount.
155 // @return Some if the operation succeeds.
156 // Error if the operation fails.
158  const std::string& hierarchy,
159  const std::string& subsystems,
160  int retry = 0);
161 
162 
163 // Unmount the cgroups virtual file system from the given hierarchy
164 // root. The caller must make sure to remove all cgroups in the
165 // hierarchy before unmount. This function assumes the given hierarchy
166 // is currently mounted with a cgroups virtual file system. It will
167 // return error if the given hierarchy has any cgroups.
168 // @param hierarchy Path to the hierarchy root.
169 // @return Some if the operation succeeds.
170 // Error if the operation fails.
171 Try<Nothing> unmount(const std::string& hierarchy);
172 
173 
174 // Returns true if the given hierarchy root is mounted as a cgroups
175 // virtual file system with the specified subsystems attached.
176 // @param hierarchy Path to the hierarchy root.
177 // @return True if the given directory is a hierarchy root and all of the
178 // specified subsystems are attached.
179 // False if the directory is not a hierarchy (or doesn't exist)
180 // or some of the specified subsystems are not attached.
181 // Error if the operation fails.
183  const std::string& hierarchy,
184  const std::string& subsystems = "");
185 
186 
187 // Create a cgroup in a given hierarchy. To create a cgroup, one just
188 // needs to create a directory in the cgroups virtual file system. The
189 // given cgroup is a relative path to the given hierarchy. This
190 // function assumes the given hierarchy is valid and is currently
191 // mounted with a cgroup virtual file system. The function also
192 // assumes the given cgroup is valid.
193 // @param hierarchy Path to the hierarchy root.
194 // @param cgroup Path to the cgroup relative to the hierarchy root.
195 // @param recursive Will create nested cgroups
196 // @return Some if the operation succeeds.
197 // Error if the operation fails.
199  const std::string& hierarchy,
200  const std::string& cgroup,
201  bool recursive = false);
202 
203 
204 // Returns true if the given cgroup under a given hierarchy exists.
205 // @param hierarchy Path to the hierarchy root.
206 // @param cgroup Path to the cgroup relative to the hierarchy root.
207 // @return True if the cgroup exists.
208 // False if the cgroup does not exist.
209 bool exists(const std::string& hierarchy, const std::string& cgroup);
210 
211 
212 // Return all the cgroups under the given cgroup of a given hierarchy.
213 // By default, it returns all the cgroups under the given hierarchy.
214 // This function assumes that the given hierarchy and cgroup are
215 // valid. We use a post-order walk here to ease the removal of
216 // cgroups.
217 // @param hierarchy Path to the hierarchy root.
218 // @return A vector of cgroup names.
220  const std::string& hierarchy,
221  const std::string& cgroup = "/");
222 
223 
224 // Send the specified signal to all process in a cgroup. This function
225 // assumes that the given hierarchy and cgroup are valid.
226 // @param hierarchy Path to the hierarchy root.
227 // @param cgroup Path to the cgroup relative to the hierarchy root.
228 // @param signal The signal to send to all tasks within the cgroup.
229 // @return Some on success.
230 // Error if something unexpected happens.
232  const std::string& hierarchy,
233  const std::string& cgroup,
234  int signal);
235 
236 
237 // Read a control file. Control files are the gateway to monitor and
238 // control cgroups. This function assumes the cgroups virtual file
239 // systems are properly mounted on the given hierarchy, and the given
240 // cgroup has been already created properly. The given control file
241 // name should also be valid.
242 // @param hierarchy Path to the hierarchy root.
243 // @param cgroup Path to the cgroup relative to the hierarchy root.
244 // @param control Name of the control file.
245 // @return The value read from the control file.
247  const std::string& hierarchy,
248  const std::string& cgroup,
249  const std::string& control);
250 
251 
252 // Write a control file. This function assumes the cgroups virtual
253 // file systems are properly mounted on the given hierarchy, and the
254 // given cgroup has been already created properly. The given control
255 // file name should also be valid.
256 // @param hierarchy Path to the hierarchy root.
257 // @param cgroup Path to the cgroup relative to the hierarchy root.
258 // @param control Name of the control file.
259 // @param value Value to be written.
260 // @return Some if the operation succeeds.
261 // Error if the operation fails.
263  const std::string& hierarchy,
264  const std::string& cgroup,
265  const std::string& control,
266  const std::string& value);
267 
268 
269 // Check whether a control file is valid under a given cgroup and a
270 // given hierarchy. This function will return error if the given
271 // hierarchy is not properly mounted with appropriate subsystems, or
272 // the given cgroup does not exist, or the control file does not
273 // exist.
274 // @param hierarchy Path to the hierarchy root.
275 // @param cgroup Path to the cgroup relative to the hierarchy root.
276 // @param control Name of the control file.
277 // @return True if the check succeeds.
278 // False if the check fails.
279 bool exists(
280  const std::string& hierarchy,
281  const std::string& cgroup,
282  const std::string& control);
283 
284 
285 // Return the set of process IDs in a given cgroup under a given
286 // hierarchy. It assumes the given hierarchy and cgroup are valid.
287 // @param hierarchy Path to the hierarchy root.
288 // @param cgroup Path to the cgroup relative to the hierarchy root.
289 // @return The set of process ids.
291  const std::string& hierarchy,
292  const std::string& cgroup);
293 
294 
295 // Return the set of thread IDs in a given cgroup under a given
296 // hierarchy. It assumes the given hierarchy and cgroup are valid.
297 // @param hierarchy Path to the hierarchy root.
298 // @param cgroup Path to the cgroup relative to the hierarchy root.
299 // @return The set of thread ids.
301  const std::string& hierarchy,
302  const std::string& cgroup);
303 
304 
305 // Assign a given process specified by its pid to a given cgroup. All
306 // threads in the pid's threadgroup will also be moved to the cgroup.
307 // This function assumes the given hierarchy and cgroup are valid. It
308 // will return error if the pid has no process associated with it.
309 // @param hierarchy Path to the hierarchy root.
310 // @param cgroup Path to the cgroup relative to the hierarchy root.
311 // @param pid The pid of the given process.
312 // @return Some if the operation succeeds.
313 // Error if the operation fails.
315  const std::string& hierarchy,
316  const std::string& cgroup,
317  pid_t pid);
318 
319 
320 // Isolate a given process specified by its 'pid' to a given cgroup by
321 // both creating the cgroup (recursively) if it doesn't exist and then
322 // assigning the process to that cgroup. It assumes the hierarchy is
323 // valid.
324 // @param hierarchy Path to the hierarchy root.
325 // @param cgroup Path to the cgroup relative to the hierarchy root.
326 // @param pid The pid of the given process.
327 // @return Nothing if the operation succeeds.
328 // Error if the operation fails.
330  const std::string& hierarchy,
331  const std::string& cgroup,
332  pid_t pid);
333 
334 
335 namespace event {
336 
337 // Listen on an event notifier and return a future which will become
338 // ready when the certain event happens. This function assumes the
339 // given hierarchy, cgroup and control file are valid.
340 // @param hierarchy Path to the hierarchy root.
341 // @param cgroup Path to the cgroup relative to the hierarchy root.
342 // @param control Name of the control file.
343 // @param args Control specific arguments.
344 // @return A future which contains the value read from the file when ready.
345 // Error if something unexpected happens.
347  const std::string& hierarchy,
348  const std::string& cgroup,
349  const std::string& control,
351 
352 } // namespace event {
353 
354 
355 // Destroy a cgroup under a given hierarchy. It will also recursively
356 // destroy any sub-cgroups. If the freezer subsystem is attached to
357 // the hierarchy, we attempt to kill all tasks in a given cgroup,
358 // before removing it. Otherwise, we just attempt to remove the
359 // cgroup. This function assumes the given hierarchy and cgroup are
360 // valid. It returns error if we failed to destroy any of the cgroups.
361 // NOTE: If cgroup is "/" (default), all cgroups under the
362 // hierarchy are destroyed.
363 // TODO(vinod): Add support for killing tasks when freezer subsystem
364 // is not present.
365 // @param hierarchy Path to the hierarchy root.
366 // @param cgroup Path to the cgroup relative to the hierarchy root.
367 // @return A future which will become ready when the operation is done.
368 // Error if something unexpected happens.
370  const std::string& hierarchy,
371  const std::string& cgroup = "/");
372 
373 
374 // Destroy a cgroup under a given hierarchy. This is a convenience
375 // function which wraps the cgroups::destroy() to add a timeout: if
376 // the cgroup(s) cannot be destroyed after timeout the operation will
377 // be discarded.
379  const std::string& hierarchy,
380  const std::string& cgroup,
381  const Duration& timeout);
382 
383 
384 // Cleanup the hierarchy, by first destroying all the underlying
385 // cgroups, unmounting the hierarchy and deleting the mount point.
386 // @param hierarchy Path to the hierarchy root.
387 // @return A future which will become ready when the operation is done.
388 // Error if something unexpected happens.
389 process::Future<bool> cleanup(const std::string& hierarchy);
390 
391 
392 // Returns the stat information from the given file. This function
393 // assumes the given hierarchy and cgroup are valid.
394 // @param hierarchy Path to the hierarchy root.
395 // @param cgroup Path to the cgroup relative to the hierarchy root.
396 // @param file The stat file to read from. (Ex: "memory.stat").
397 // @return The stat information parsed from the file.
398 // Error if reading or parsing fails.
399 // TODO(bmahler): Consider namespacing stat for each subsystem (e.g.
400 // cgroups::memory::stat and cgroups::cpuacct::stat).
402  const std::string& hierarchy,
403  const std::string& cgroup,
404  const std::string& file);
405 
406 
407 // Blkio subsystem.
408 namespace blkio {
409 
410 // Returns the cgroup that the specified pid is a member of within the
411 // hierarchy that the 'blkio' subsystem is mounted, or None if the subsystem
412 // is not mounted or the pid is not a member of a cgroup.
414 
415 
416 // Wrapper class for dev_t.
417 class Device
418 {
419 public:
420  constexpr Device(dev_t device) : value(device) {}
421  unsigned int getMajor() const;
422  unsigned int getMinor() const;
423 
424  inline bool operator==(const Device& that) const
425  {
426  return value == that.value;
427  }
428 
429  inline bool operator!=(const Device& that) const
430  {
431  return value != that.value;
432  }
433 
434  inline operator dev_t() const { return value; }
435 
436 public:
437  static Try<Device> parse(const std::string& s);
438 
439 private:
440  dev_t value;
441 };
442 
443 
444 enum class Operation {
445  TOTAL,
446  READ,
447  WRITE,
448  SYNC,
449  ASYNC,
450  DISCARD,
451 };
452 
453 
454 // Entry for a blkio file. The format of each entry can either be:
455 // 1. <value>
456 // 2. <dev> <value>
457 // 3. <dev> <op> <value>
458 // 4. <op> <value>
459 //
460 // For details:
461 // https://www.kernel.org/doc/Documentation/cgroup-v1/blkio-controller.txt
462 struct Value
463 {
466  uint64_t value;
467 
468  static Try<Value> parse(const std::string& s);
469 };
470 
471 
472 namespace cfq {
473 
475  const std::string& hierarchy,
476  const std::string& cgroup);
477 
478 
480  const std::string& hierarchy,
481  const std::string& cgroup);
482 
483 
485  const std::string& hierarchy,
486  const std::string& cgroup);
487 
488 
490  const std::string& hierarchy,
491  const std::string& cgroup);
492 
493 
494 // Returns the total number of bios/requests merged into requests
495 // belonging to the given cgroup from blkio.io_merged. This function
496 // assumes the given hierarchy and cgroup are valid.
498  const std::string& hierarchy,
499  const std::string& cgroup);
500 
501 
502 // Returns the total number of bios/requests merged into requests
503 // belonging to the given cgroup and all its descendants from
504 // blkio.io_merged_recursive. This function assumes the given
505 // hierarchy and cgroup are valid.
507  const std::string& hierarchy,
508  const std::string& cgroup);
509 
510 
511 // Returns the total number of requests queued up in the given
512 // cgroup from blkio.io_queued. This function assumes the given
513 // hierarchy and cgroup are valid.
515  const std::string& hierarchy,
516  const std::string& cgroup);
517 
518 
519 // Returns the total number of requests queued up in the given
520 // cgroup and all its descendants from blkio.io_queued_recursive.
521 // This function assumes the given hierarchy and cgroup are valid.
523  const std::string& hierarchy,
524  const std::string& cgroup);
525 
526 
527 // Returns the number of bytes transferred to/from the disk by the
528 // given cgroup from blkio.io_service_bytes. This function assumes the
529 // given hierarchy and cgroup are valid.
531  const std::string& hierarchy,
532  const std::string& cgroup);
533 
534 
535 // Returns the number of bytes transferred to/from the disk by the
536 // given cgroup and all its descendants from
537 // blkio.io_service_bytes_recursive. This function assumes the given
538 // hierarchy and cgroup are valid.
540  const std::string& hierarchy,
541  const std::string& cgroup);
542 
543 
544 // Returns the total amount of time between request dispatch and
545 // completion by the IOs done by the given cgroup from
546 // blkio.io_service_time. This function assumes the given hierarchy
547 // and cgroup are valid.
549  const std::string& hierarchy,
550  const std::string& cgroup);
551 
552 
553 // Returns the total amount of time between request dispatch and
554 // completion by the IOs done by the given cgroup and all its
555 // descendants from blkio.io_service_time_recursive. This function
556 // assumes the given hierarchy and cgroup are valid.
558  const std::string& hierarchy,
559  const std::string& cgroup);
560 
561 
562 // Returns the number of IOs (bio) issued to the disk by the given
563 // cgroup from blkio.io_serviced. This function assumes the given
564 // hierarchy and cgroup are valid.
566  const std::string& hierarchy,
567  const std::string& cgroup);
568 
569 
570 // Returns the number of IOs (bio) issued to the disk by the given
571 // cgroup and all its descendants from blkio.io_serviced_recursive.
572 // This function assumes the given hierarchy and cgroup are valid.
574  const std::string& hierarchy,
575  const std::string& cgroup);
576 
577 
578 // Returns the total amount of time the IOs for the given cgroup spent
579 // waiting in the schedule queues for service from blkio.io_wait_time.
580 // This function assumes the given hierarchy and cgroup are valid.
582  const std::string& hierarchy,
583  const std::string& cgroup);
584 
585 
586 // Returns the total amount of time the IOs for the given cgroup and
587 // all its descendants spent waiting in the scheduler queues for
588 // service from blkio.io_wait_time_recursive. This function assumes
589 // the given hierarchy and cgroup are valid.
591  const std::string& hierarchy,
592  const std::string& cgroup);
593 
594 } // namespace cfq {
595 
596 
597 namespace throttle {
598 
599 // Returns the numbers of bytes transferred to/from the disk for the
600 // given cgroup from blkio.throttle.io_service_bytes. This function
601 // assumes the given hierarchy and cgroup are valid.
603  const std::string& hierarchy,
604  const std::string& cgroup);
605 
606 
607 // Returns the numbers of IOs (bio) issued to the disk for the given
608 // cgroup from blkio.throttle.io_serviced. This function assumes the
609 // given hierarchy and cgroup are valid.
611  const std::string& hierarchy,
612  const std::string& cgroup);
613 
614 } // namespace throttle {
615 
616 
617 inline std::ostream& operator<<(std::ostream& stream, const Device& device)
618 {
619  return stream << device.getMajor() << ':' << device.getMinor();
620 }
621 
622 
623 inline std::ostream& operator<<(std::ostream& stream, const Operation op)
624 {
625  switch (op) {
626  case Operation::TOTAL:
627  return stream << "Total";
628  case Operation::READ:
629  return stream << "Read";
630  case Operation::WRITE:
631  return stream << "Write";
632  case Operation::SYNC:
633  return stream << "Sync";
634  case Operation::ASYNC:
635  return stream << "Async";
636  case Operation::DISCARD:
637  return stream << "Discard";
638  }
639 
640  UNREACHABLE();
641 }
642 
643 
644 inline std::ostream& operator<<(std::ostream& stream, const Value& value)
645 {
646  if (value.device.isSome()) {
647  stream << value.device.get() << ' ';
648  }
649 
650  if (value.op.isSome()) {
651  stream << value.op.get() << ' ';
652  }
653 
654  return stream << value.value;
655 }
656 
657 } // namespace blkio {
658 
659 
660 // Cpu controls.
661 namespace cpu {
662 
663 // Returns the cgroup that the specified pid is a member of within the
664 // hierarchy that the 'cpu' subsystem is mounted or None if the
665 // subsystem is not mounted or the pid is not a member of a cgroup.
667 
668 
669 // Sets the cpu shares using cpu.shares. This function assumes the
670 // given hierarchy and cgroup are valid.
672  const std::string& hierarchy,
673  const std::string& cgroup,
674  uint64_t shares);
675 
676 
677 // Returns the cpu shares from cpu.shares. This function assumes the
678 // given hierarchy and cgroup are valid.
680  const std::string& hierarchy,
681  const std::string& cgroup);
682 
683 
684 // Sets the cfs period using cpu.cfs_period_us. This function assumes
685 // the given hierarchy and cgroup are valid.
687  const std::string& hierarchy,
688  const std::string& cgroup,
689  const Duration& duration);
690 
691 
692 // Returns the cfs quota from cpu.cfs_quota_us. This function assumes
693 // the given hierarchy and cgroup are valid.
695  const std::string& hierarchy,
696  const std::string& cgroup);
697 
698 
699 // Sets the cfs quota using cpu.cfs_quota_us. This function assumes
700 // the given hierarchy and cgroup are valid.
702  const std::string& hierarchy,
703  const std::string& cgroup,
704  const Duration& duration);
705 
706 } // namespace cpu {
707 
708 
709 // Cpuacct subsystem.
710 namespace cpuacct {
711 
712 // Returns the cgroup that the specified pid is a member of within the
713 // hierarchy that the 'cpuacct' subsytem is mounted or None if the
714 // subsystem is not mounted or the pid is not a member of a cgroup.
715 //
716 // @param pid process id for which cgroup is queried within the cpuacct
717 // subsytem.
718 // @return Some cgroup in case there was a valid cgroup found for the pid.
719 // Error if there was any error in processing.
721 
722 
723 // Encapsulates the 'stat' information exposed by the cpuacct subsystem.
724 struct Stats
725 {
726  const Duration user;
728 };
729 
730 
731 // Returns 'Stats' for a given hierarchy and cgroup. This function
732 // assumes the given hierarchy and cgroup are valid.
733 //
734 // @param hierarchy hierarchy for the 'cpuacct' subsystem.
735 // @param cgroup cgroup for a given process.
736 // @return Some<Stats> if successful.
737 // Error in case of any error during processing.
739  const std::string& hierarchy,
740  const std::string& cgroup);
741 
742 } // namespace cpuacct {
743 
744 
745 // Memory controls.
746 namespace memory {
747 
748 // Returns the cgroup that the specified pid is a member of within the
749 // hierarchy that the 'memory' subsytem is mounted or None if the
750 // subsystem is not mounted or the pid is not a member of a cgroup.
752 
753 
754 // Returns the memory limit from memory.limit_in_bytes. This function
755 // assumes the given hierarchy and cgroup are valid.
757  const std::string& hierarchy,
758  const std::string& cgroup);
759 
760 
761 // Sets the memory limit using memory.limit_in_bytes. This function
762 // assumes the given hierarchy and cgroup are valid.
764  const std::string& hierarchy,
765  const std::string& cgroup,
766  const Bytes& limit);
767 
768 
769 // Returns the memory limit from memory.memsw.limit_in_bytes. Returns
770 // none if memory.memsw.limit_in_bytes is not supported (e.g., when
771 // swap is turned off). This function assumes the given hierarchy and
772 // cgroup are valid.
774  const std::string& hierarchy,
775  const std::string& cgroup);
776 
777 
778 // Sets the memory limit using memory.memsw.limit_in_bytes. Returns
779 // false if memory.memsw.limit_in_bytes is not supported (e.g., when
780 // swap is turned off). This function assumes the given hierarchy and
781 // cgroup are valid.
783  const std::string& hierarchy,
784  const std::string& cgroup,
785  const Bytes& limit);
786 
787 
788 // Returns the soft memory limit from memory.soft_limit_in_bytes. This
789 // function assumes the given hierarchy and cgroup are valid.
791  const std::string& hierarchy,
792  const std::string& cgroup);
793 
794 
795 // Sets the soft memory limit using memory.soft_limit_in_bytes. This
796 // function assumes the given hierarchy and cgroup are valid.
798  const std::string& hierarchy,
799  const std::string& cgroup,
800  const Bytes& limit);
801 
802 
803 // Returns the memory usage from memory.usage_in_bytes. This function
804 // assumes the given hierarchy and cgroup are valid.
806  const std::string& hierarchy,
807  const std::string& cgroup);
808 
809 
810 // Returns the memory + swap usage from memory.memsw.usage_in_bytes.
811 // This function assumes the given hierarchy and cgroup are valid.
813  const std::string& hierarchy,
814  const std::string& cgroup);
815 
816 
817 // Returns the max memory usage from memory.max_usage_in_bytes. This
818 // function assumes the given hierarchy and cgroup are valid.
820  const std::string& hierarchy,
821  const std::string& cgroup);
822 
823 
824 // Out-of-memory (OOM) controls.
825 namespace oom {
826 
827 // Listen for an OOM event for the cgroup. This function assumes the
828 // given hierarchy and cgroup are valid.
830  const std::string& hierarchy,
831  const std::string& cgroup);
832 
833 // OOM killer controls.
834 namespace killer {
835 
836 // Return whether the kernel OOM killer is enabled for the cgroup.
837 // This function assumes the given hierarchy and cgroup are valid.
839  const std::string& hierarchy,
840  const std::string& cgroup);
841 
842 // Enable the kernel OOM killer for the cgroup. The control file will
843 // only be written to if necessary. This function assumes the given
844 // hierarchy and cgroup are valid.
846  const std::string& hierarchy,
847  const std::string& cgroup);
848 
849 // Disable the kernel OOM killer. The control file will only be
850 // written to if necessary. This function assumes the given hierarchy
851 // and cgroup are valid.
853  const std::string& hierarchy,
854  const std::string& cgroup);
855 
856 } // namespace killer {
857 
858 } // namespace oom {
859 
860 
861 // Memory pressure counters.
862 namespace pressure {
863 
864 enum Level
865 {
869 };
870 
871 
872 std::ostream& operator<<(std::ostream& stream, Level level);
873 
874 
875 // Forward declaration.
876 class CounterProcess;
877 
878 
879 // Counter is a primitive to listen on events of a given memory
880 // pressure level for a cgroup and keep track of the number of
881 // occurrence of that event. Use the public 'create' function to
882 // create a new counter; see 'value' for how to use.
883 class Counter
884 {
885 public:
886  // Create a memory pressure counter for the given cgroup on the
887  // specified level. This function assumes the given hierarchy and
888  // cgroup are valid.
890  const std::string& hierarchy,
891  const std::string& cgroup,
892  Level level);
893 
894  virtual ~Counter();
895 
896  // Returns the current accumulated number of occurrences of the
897  // pressure event. Returns a failure if any error occurs while
898  // monitoring the pressure events, and any subsequent calls to
899  // 'value' will return the same failure. In such case, the user
900  // should consider creating a new Counter.
901  process::Future<uint64_t> value() const;
902 
903 private:
904  Counter(const std::string& hierarchy,
905  const std::string& cgroup,
906  Level level);
907 
909 };
910 
911 } // namespace pressure {
912 
913 } // namespace memory {
914 
915 
916 // Device controls.
917 namespace devices {
918 
919 struct Entry
920 {
921  static Try<Entry> parse(const std::string& s);
922 
923  struct Selector
924  {
925  enum class Type
926  {
927  ALL,
928  BLOCK,
929  CHARACTER,
930  };
931 
933  Option<unsigned int> major; // Matches all `major` numbers if None.
934  Option<unsigned int> minor; // Matches all `minor` numbers if None.
935  };
936 
937  struct Access
938  {
939  bool read;
940  bool write;
941  bool mknod;
942  };
943 
946 };
947 
948 std::ostream& operator<<(
949  std::ostream& stream,
950  const Entry::Selector::Type& type);
951 
952 std::ostream& operator<<(
953  std::ostream& stream,
954  const Entry::Selector& selector);
955 
956 std::ostream& operator<<(
957  std::ostream& stream,
958  const Entry::Access& access);
959 
960 std::ostream& operator<<(
961  std::ostream& stream,
962  const Entry& entry);
963 
964 
965 bool operator==(
966  const Entry::Selector& left,
967  const Entry::Selector& right);
968 
969 bool operator==(
970  const Entry::Access& left,
971  const Entry::Access& right);
972 
973 bool operator==(
974  const Entry& left,
975  const Entry& right);
976 
977 
978 // Returns the entries within devices.list. This function assumes the
979 // given hierarchy and cgroup are valid.
981  const std::string& hierarchy,
982  const std::string& cgroup);
983 
984 // Writes the provided `entry` into devices.allow. This function
985 // assumes the given hierarchy and cgroup are valid.
987  const std::string& hierarchy,
988  const std::string& cgroup,
989  const Entry& entry);
990 
991 // Writes the provided `entry` into devices.deny. This function
992 // assumes the given hierarchy and cgroup are valid.
994  const std::string& hierarchy,
995  const std::string& cgroup,
996  const Entry& entry);
997 
998 } // namespace devices {
999 
1000 
1001 // Freezer controls.
1002 // The freezer can be in one of three states:
1003 // 1. THAWED : No process in the cgroup is frozen.
1004 // 2. FREEZING : Freezing is in progress but not all processes are frozen.
1005 // 3. FROZEN : All processes are frozen.
1006 namespace freezer {
1007 
1008 // Freeze all processes in the given cgroup. This function will return
1009 // a future which will become ready when all processes have been
1010 // frozen (cgroup is in the FROZEN state). This function assumes the
1011 // given hierarchy and cgroup are valid.
1013  const std::string& hierarchy,
1014  const std::string& cgroup);
1015 
1016 
1017 // Thaw all processes in the given cgroup. This is a revert operation
1018 // of freezer::freeze. This function will return a future which will
1019 // become ready when all processes have been thawed (cgroup is in the
1020 // THAWED state). This function assumes the given hierarchy and cgroup
1021 // are valid.
1023  const std::string& hierarchy,
1024  const std::string& cgroup);
1025 
1026 } // namespace freezer {
1027 
1028 
1029 // Net_cls subsystem.
1030 namespace net_cls {
1031 
1032 // Read the uint32_t handle set in `net_cls.classid`. This function
1033 // assumes the given hierarchy and cgroup are valid.
1035  const std::string& hierarchy,
1036  const std::string& cgroup);
1037 
1038 
1039 // Write the uint32_t handle to the `net_cls.classid`. This function
1040 // assumes the given hierarchy and cgroup are valid.
1042  const std::string& hierarchy,
1043  const std::string& cgroup,
1044  const uint32_t handle);
1045 
1046 } // namespace net_cls {
1047 
1048 
1049 // Named hierarchy.
1050 namespace named {
1051 
1052 // Returns the cgroup that the specified pid is a member of within the
1053 // given named hierarchy is mounted or None if the named hierarchy is
1054 // not mounted or the pid is not a member of a cgroup.
1055 Result<std::string> cgroup(const std::string& hierarchyName, pid_t pid);
1056 
1057 } // namespace named {
1058 
1059 
1060 } // namespace cgroups {
1061 
1062 namespace std {
1063 
1064 template <>
1066 {
1067  typedef size_t result_type;
1068 
1070 
1071  result_type operator()(const argument_type& level) const
1072  {
1073  // Use the underlying type of the enum as hash value.
1074  return static_cast<size_t>(level);
1075  }
1076 };
1077 
1078 } // namespace std {
1079 
1080 #endif // __CGROUPS_HPP__
const short READ
A possible event while polling.
Definition: io.hpp:34
Try< Nothing > isolate(const std::string &hierarchy, const std::string &cgroup, pid_t pid)
Try< std::vector< Value > > sectors(const std::string &hierarchy, const std::string &cgroup)
std::ostream & operator<<(std::ostream &stream, const Entry &entry)
bool mknod
Definition: cgroups.hpp:941
Try< Nothing > enable(const std::string &hierarchy, const std::string &cgroup)
Try< bool > memsw_limit_in_bytes(const std::string &hierarchy, const std::string &cgroup, const Bytes &limit)
Definition: cgroups.hpp:919
Option< unsigned int > minor
Definition: cgroups.hpp:934
Try< std::vector< Value > > io_serviced(const std::string &hierarchy, const std::string &cgroup)
Definition: check.hpp:33
Try< bool > busy(const std::string &subsystems)
Try< std::vector< Value > > io_wait_time(const std::string &hierarchy, const std::string &cgroup)
Definition: cgroups.hpp:923
const int ALL
Definition: diagnosis.hpp:52
Option< Operation > op
Definition: cgroups.hpp:465
Try< Bytes > max_usage_in_bytes(const std::string &hierarchy, const std::string &cgroup)
process::Future< bool > cleanup(const std::string &hierarchy)
Try< std::vector< Value > > io_queued_recursive(const std::string &hierarchy, const std::string &cgroup)
Try< Bytes > memsw_usage_in_bytes(const std::string &hierarchy, const std::string &cgroup)
Try< std::vector< Value > > time_recursive(const std::string &hierarchy, const std::string &cgroup)
Definition: cgroups.hpp:39
Definition: type_utils.hpp:619
bool write
Definition: cgroups.hpp:940
result_type operator()(const argument_type &level) const
Definition: cgroups.hpp:1071
Operation
Definition: cgroups.hpp:444
uint64_t value
Definition: cgroups.hpp:466
cgroups::memory::pressure::Level argument_type
Definition: cgroups.hpp:1069
const Duration system
Definition: cgroups.hpp:727
const unsigned int THREAD_ASSIGN_RETRIES
Definition: cgroups.hpp:48
unsigned int getMinor() const
Definition: duration.hpp:32
Definition: check.hpp:30
Definition: cgroups.hpp:868
process::Future< uint64_t > listen(const std::string &hierarchy, const std::string &cgroup, const std::string &control, const Option< std::string > &args=Option< std::string >::none())
Try< bool > access(const std::string &path, int how)
Definition: access.hpp:28
bool isSome() const
Definition: option.hpp:116
Try< std::vector< Value > > io_queued(const std::string &hierarchy, const std::string &cgroup)
Definition: cgroups.hpp:937
Try< std::vector< Value > > sectors_recursive(const std::string &hierarchy, const std::string &cgroup)
Try< std::vector< Value > > io_service_bytes(const std::string &hierarchy, const std::string &cgroup)
DWORD pid_t
Definition: windows.hpp:181
Definition: cgroups.hpp:866
Definition: cgroups.hpp:867
Try< std::vector< Value > > io_service_time(const std::string &hierarchy, const std::string &cgroup)
URI file(const std::string &path)
Creates a file URI with the given path on the local host.
Definition: file.hpp:33
Type
Definition: cgroups.hpp:925
Definition: cgroups.hpp:417
Try< Nothing > unmount(const std::string &hierarchy)
Try< Nothing > disable(const std::string &hierarchy, const std::string &cgroup)
Definition: duration.hpp:207
Try< Nothing > verify(const std::string &hierarchy, const std::string &cgroup="", const std::string &control="")
const short WRITE
A possible event while polling.
Definition: io.hpp:40
Try< Nothing > cfs_period_us(const std::string &hierarchy, const std::string &cgroup, const Duration &duration)
Selector selector
Definition: cgroups.hpp:944
Try< std::vector< Value > > io_service_bytes_recursive(const std::string &hierarchy, const std::string &cgroup)
Try< Nothing > limit_in_bytes(const std::string &hierarchy, const std::string &cgroup, const Bytes &limit)
Result< std::string > cgroup(const std::string &hierarchyName, pid_t pid)
Try< ImageManifest > parse(const std::string &value)
Definition: parse.hpp:36
const Duration FREEZE_RETRY_INTERVAL
Definition: cgroups.hpp:44
const T & get() const &
Definition: option.hpp:119
process::Future< Nothing > destroy(const std::string &hierarchy, const std::string &cgroup="/")
Definition: cgroups.hpp:462
Try< hashmap< std::string, uint64_t > > stat(const std::string &hierarchy, const std::string &cgroup, const std::string &file)
Try< std::vector< Value > > io_merged(const std::string &hierarchy, const std::string &cgroup)
Try< std::vector< Value > > io_wait_time_recursive(const std::string &hierarchy, const std::string &cgroup)
#define UNREACHABLE()
Definition: unreachable.hpp:22
Try< std::vector< Entry > > list(const std::string &hierarchy, const std::string &cgroup)
Try< bool > mounted(const std::string &hierarchy, const std::string &subsystems="")
Option< unsigned int > major
Definition: cgroups.hpp:933
Try< Nothing > cfs_quota_us(const std::string &hierarchy, const std::string &cgroup, const Duration &duration)
Result< Process > process(pid_t pid)
Definition: freebsd.hpp:30
Try< std::vector< Value > > io_serviced_recursive(const std::string &hierarchy, const std::string &cgroup)
bool operator==(const Path &left, const Path &right)
Definition: path.hpp:481
constexpr Device(dev_t device)
Definition: cgroups.hpp:420
Try< Nothing > mount(const std::string &hierarchy, const std::string &subsystems, int retry=0)
bool read
Definition: cgroups.hpp:939
bool operator!=(const Device &that) const
Definition: cgroups.hpp:429
Access access
Definition: cgroups.hpp:945
Try< std::set< pid_t > > processes(const std::string &hierarchy, const std::string &cgroup)
Try< Bytes > usage_in_bytes(const std::string &hierarchy, const std::string &cgroup)
Definition: cgroups.hpp:883
Try< Nothing > classid(const std::string &hierarchy, const std::string &cgroup, const uint32_t handle)
process::Future< Nothing > freeze(const std::string &hierarchy, const std::string &cgroup)
Try< uint32_t > type(const std::string &path)
Try< Nothing > allow(const std::string &hierarchy, const std::string &cgroup, const Entry &entry)
Level
Definition: cgroups.hpp:864
Try< std::vector< Value > > io_merged_recursive(const std::string &hierarchy, const std::string &cgroup)
Option< Device > device
Definition: cgroups.hpp:464
Try< std::set< std::string > > hierarchies()
Definition: cgroups.hpp:724
bool enabled()
Try< std::string > prepare(const std::string &baseHierarchy, const std::string &subsystem, const std::string &cgroup)
Try< Nothing > create(const std::string &hierarchy, const std::string &cgroup, bool recursive=false)
Try< Nothing > kill(const std::string &hierarchy, const std::string &cgroup, int signal)
Definition: bytes.hpp:30
size_t result_type
Definition: cgroups.hpp:1067
Result< std::string > hierarchy(const std::string &subsystems)
Try< Memory > memory()
Definition: freebsd.hpp:78
const Duration user
Definition: cgroups.hpp:726
bool exists(const std::string &hierarchy, const std::string &cgroup)
Try< Nothing > assign(const std::string &hierarchy, const std::string &cgroup, pid_t pid)
Type type
Definition: cgroups.hpp:932
Try< Nothing > write(const std::string &hierarchy, const std::string &cgroup, const std::string &control, const std::string &value)
Try< std::set< pid_t > > threads(const std::string &hierarchy, const std::string &cgroup)
Try< Nothing > deny(const std::string &hierarchy, const std::string &cgroup, const Entry &entry)
Try< std::vector< Value > > io_service_time_recursive(const std::string &hierarchy, const std::string &cgroup)
Try< Nothing > soft_limit_in_bytes(const std::string &hierarchy, const std::string &cgroup, const Bytes &limit)
Try< std::vector< Value > > time(const std::string &hierarchy, const std::string &cgroup)
Try< std::set< std::string > > subsystems()
Try< std::string > read(const std::string &hierarchy, const std::string &cgroup, const std::string &control)
bool operator==(const Device &that) const
Definition: cgroups.hpp:424
unsigned int getMajor() const
Try< uint64_t > shares(const std::string &hierarchy, const std::string &cgroup)
Definition: future.hpp:58
process::Future< Nothing > thaw(const std::string &hierarchy, const std::string &cgroup)