move to another system to dev

lib/Sys/Linux/Cgroup.pm

@@ -42,21 +42,23 @@ With this you can restrict a lot of the memory options for processes.  For detai
 
 =head2 CPU
 
+Control the amount cpu time allocated to all processes in the group.
+
 =head2 I/O
 
+Restricts/controls the amount of IO and latency of the io for the group.  Let's you prevent the group from starving other things running on the system.
+
 =head2 Network
 
 This controller groups all the network traffic being used by the processes, both with latency and bandwidth.  Very useful for testing or preventing a run-away process from eating up all the bandwidth during an upload, copy or some other operation
 
 =head2 Devices
 
-This lets you restrict the 
+This lets you restrict the creation of and use of device files, i.e. /dev/*, it requires the cgroup BPF support and for you to add a BPF_CGROUP_DEVICE program to attach to the group.  This will require some other libraries to support those programs.
 
 =head2 Freezer
 
-This one isn't quite the same as the others, it doesn't restrict any actual resource units but does let you stop all of the processes in the group.
-It can be polled to find out if all of the processes are stopped, and carrys on to all child cgroups and child processes automatically.  This lets you
-stop all processes to send them a signal, e.g. SIGKILL, without worrying that they're spawning new children while you try to signal them.  In version 2, this is a property of the group as a whole and not a separate controller.
+This one isn't quite the same as the others, it doesn't restrict any actual resource units but does let you stop all of the processes in the group. It can be polled to find out if all of the processes are stopped, and carrys on to all child cgroups and child processes automatically.  This lets you stop all processes to send them a signal, e.g. SIGKILL, without worrying that they're spawning new children while you try to signal them.  In version 2, this is a property of the group as a whole and not a separate controller.
 
 See L<Sys::Linux::Cgroup::V1::Freezer> or L<Sys::Linux::Cgroup::V2>
 
@@ -64,7 +66,7 @@ N.B. To be truly race-free for sending signals or doing other things with the pr
 
 =head2 RDMA
 
-This one is going to be the last I implement, simply because it's utility for perl code is likely to be very very low.  It deals with how many RDMA handles can be allocated.  Might be useful to have for perl code that manages other processes but that's about it.
+This one is going to be the last I implement, simply because it's utility for perl code is likely to be very very low.  It deals with how many RDMA handles can be allocated.  Might be useful to have for perl code that manages other processes but that's about it.  Also I don't have any way to test it properly.
 
 =head2 perf_event
 

lib/Sys/Linux/Cgroup/Setup.pod

@@ -0,0 +1,91 @@
+=head1 DESCRIPTION
+
+This is a bit of a setup guide for using this module with Systemd or cgmanager
+
+=head1 CAVEATS
+
+Right now this module does not support Cgroup V1.  I will eventually try to build that support but for now I'm only targetting v2 because of the extra features it supports.
+
+=head1 REQUIREMENTS
+
+The way that cgroup heirarchies work, you've got two kinds of things.  Branches and Leaves.  Process cannot belong to a branch node, only leaves.  The reason for this is that you can't make a sub-tree/branch under a heirarchy that has processes in it.  
+
+
+
+=head1 SYSTEMD
+
+=head1 CGMANAGER
+
+This setup will look similar to how 
+
+=head1 V1 or V2
+
+There's two versions of the cgroup api in the wild, V1 and V2.  V1 has each type of controller in it's own heirarchy, which means that you can have two different trees of cgroups for different types of resource management.  This largely turned out to be a bad idea because it made management more difficult since there's a lot more to keep track of.  It also didn't really pan out that anyone seemed to actually want the flexibility that this allowed.  V2 changed this by having a single heirarchy that starts at a root node where every process is in by default.  Then you can make children in each cgroup and enable the controllers that you want there.  
+
+=head1 CONTROLLERS
+
+The cgroup API works by classifying the types of limits you want to use, calling them Controllers. 
+
+=head2 Memory
+
+With this you can restrict a lot of the memory options for processes.  For details see L<Sys::Linux::Cgroup::Memory> # TODO make pod for this
+
+=head2 CPU
+
+Control the amount cpu time allocated to all processes in the group.
+
+=head2 I/O
+
+Restricts/controls the amount of IO and latency of the io for the group.  Let's you prevent the group from starving other things running on the system.
+
+=head2 Network
+
+This controller groups all the network traffic being used by the processes, both with latency and bandwidth.  Very useful for testing or preventing a run-away process from eating up all the bandwidth during an upload, copy or some other operation
+
+=head2 Devices
+
+This lets you restrict the creation of and use of device files, i.e. /dev/*, it requires the cgroup BPF support and for you to add a BPF_CGROUP_DEVICE program to attach to the group.  This will require some other libraries to support those programs.
+
+=head2 Freezer
+
+This one isn't quite the same as the others, it doesn't restrict any actual resource units but does let you stop all of the processes in the group. It can be polled to find out if all of the processes are stopped, and carrys on to all child cgroups and child processes automatically.  This lets you stop all processes to send them a signal, e.g. SIGKILL, without worrying that they're spawning new children while you try to signal them.  In version 2, this is a property of the group as a whole and not a separate controller.
+
+See L<Sys::Linux::Cgroup::V1::Freezer> or L<Sys::Linux::Cgroup::V2>
+
+N.B. To be truly race-free for sending signals or doing other things with the processes you will also need to use the upcoming C<pidfd> support in newer linux kernels (5.3 and above).  No library currently exists for using this from perl.  Coming Soon.
+
+=head2 RDMA
+
+This one is going to be the last I implement, simply because it's utility for perl code is likely to be very very low.  It deals with how many RDMA handles can be allocated.  Might be useful to have for perl code that manages other processes but that's about it.  Also I don't have any way to test it properly.
+
+=head2 perf_event
+
+This is also going to be a low priority as it deals with performance counters in the kernel and cpu.  This is less likely to be useful for perl code, but might be useful for monitoring the health of another program.
+
+=head1 WARRANTY
+
+This is alpha quality releases right now, there is no warranty.  You use this at your own risk.
+
+=head1 TODO
+
+=over 1
+
+=item Make TODO list
+
+=item Add cgroup v1 apis
+
+=item Add cgroup v2 apis
+
+=item Add high level api that uses either version api to accomplish the needed groupings
+
+=back
+
+=head1 SEE ALSO
+
+L<App::EvalServerAdvanced::REPL>, L<App::EvalServerAdvanced::Protocol>
+
+=head1 AUTHOR
+
+Ryan Voots <simcop@cpan.org>
+
+=cut