{"id":13605169,"url":"https://github.com/hamadmarri/cacule-cpu-scheduler","last_synced_at":"2025-10-03T14:31:39.368Z","repository":{"id":48322225,"uuid":"282162283","full_name":"hamadmarri/cacule-cpu-scheduler","owner":"hamadmarri","description":"The CacULE CPU scheduler is based on interactivity score mechanism. The interactivity score is inspired by the ULE scheduler (FreeBSD scheduler).","archived":true,"fork":false,"pushed_at":"2021-09-02T15:53:18.000Z","size":223679,"stargazers_count":266,"open_issues_count":2,"forks_count":32,"subscribers_count":24,"default_branch":"master","last_synced_at":"2024-09-29T15:01:31.355Z","etag":null,"topics":["cache","cachy","cachy-scheduler","cacule","cfs","cpu","cpu-cache","cpu-scheduler","freebsd","hrrn","linux","linux-kernel","process-scheduler","response-ratio","scheduler","ule"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hamadmarri.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG","contributing":null,"funding":".github/FUNDING.yml","license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null},"funding":{"github":null,"patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"custom":["https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick\u0026hosted_button_id=8F7F4D8BKR8XC"]}},"created_at":"2020-07-24T08:13:14.000Z","updated_at":"2024-08-04T18:46:42.000Z","dependencies_parsed_at":"2022-08-20T12:10:18.621Z","dependency_job_id":null,"html_url":"https://github.com/hamadmarri/cacule-cpu-scheduler","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hamadmarri%2Fcacule-cpu-scheduler","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hamadmarri%2Fcacule-cpu-scheduler/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hamadmarri%2Fcacule-cpu-scheduler/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hamadmarri%2Fcacule-cpu-scheduler/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hamadmarri","download_url":"https://codeload.github.com/hamadmarri/cacule-cpu-scheduler/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":235146472,"owners_count":18943264,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cache","cachy","cachy-scheduler","cacule","cfs","cpu","cpu-cache","cpu-scheduler","freebsd","hrrn","linux","linux-kernel","process-scheduler","response-ratio","scheduler","ule"],"created_at":"2024-08-01T19:00:55.378Z","updated_at":"2025-10-03T14:31:36.840Z","avatar_url":"https://github.com/hamadmarri.png","language":"C","funding_links":["https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick\u0026hosted_button_id=8F7F4D8BKR8XC"],"categories":["C","CPU Schedulers for Linux"],"sub_categories":[],"readme":"![logo](cacule_logo_gh.png)\n\nThe CacULE CPU scheduler is a CFS patchset that is based on interactivity score mechanism.\nThe interactivity score is inspired by the ULE scheduler (FreeBSD\nscheduler). The goal of this patch is to enhance system responsiveness/latency.\n\n\n## About CacULE Scheduler\n* Each CPU has its own runqueue.\n* NORMAL runqueue is a linked list of sched_entities (instead of RB-Tree).\n* RT and other runqueues are just the same as the CFS's.\n* Wake up tasks preempt currently running tasks if its interactivity score value is higher.\n\n\n## The CacULE Interactivity Score\nThe interactivity score is inspired by the ULE scheduler (FreeBSD scheduler).\nFor more information see: https://web.cs.ucdavis.edu/~roper/ecs150/ULE.pdf\nCacULE doesn't replace CFS with ULE, it only changes the CFS' pick next task\nmechanism to ULE's interactivity score mechanism for picking next task to run.\n\n### sched_interactivity_factor\nSets the value *m* for interactivity score calculations. See Figure 1 in\nhttps://web.cs.ucdavis.edu/~roper/ecs150/ULE.pdf\nThe default value of in CacULE is 32768 which means that the Maximum Interactive\nScore is 65536 (since m = Maximum Interactive Score / 2).\nYou can tune sched_interactivity_factor with sysctl command:\n\n\tsysctl kernel.sched_interactivity_factor=50\n\nThis command changes the sched_interactivity_factor from 32768 to 50.\n\n### sched_max_lifetime_ms\nInstead of calculating a task IS value for infinite life time, we use\n`sched_max_lifetime_ms` which is 22s by default. Task's `cacule_lifetime` and\n`vruntime` shrink whenever a task life time exceeds 30s. Therefore, the rate of change of IS\nfor old and new tasks is normalized. The value `sched_max_lifetime` can be\nchanged at run time by the following sysctl command:\n```\nsysctl kernel.sched_max_lifetime_ms=60000\n```\nThe value is in milliseconds, the above command changes `sched_max_lifetime`\nfrom 22s to 60s.\n\nIn the first round, when the task's life time became \u003e 22s, the `cacule_start_time`\nget reset to be (`current_time - 11s`), then, the task will keep resetting\nevery 15s.\n\n### Starve and Cache Scores\nSee [here](https://github.com/hamadmarri/cacule-cpu-scheduler/discussions/43).\n\n### sched_cacule_yield\nSee [here](https://github.com/hamadmarri/cacule-cpu-scheduler/issues/35).\n\n## Complexity\n* The complexity of Enqueue a task is O(1).\n* The complexity of Dequeue a task is O(1).\n* The complexity of pick the next task is in O(n).\n\nn is the number of tasks in a runqueue (each CPU has its own runqueue).\n\nNote: O(n) sounds scary, but usually for a machine with 4 CPUS where it is used\nfor desktop or mobile jobs, the maximum number of runnable tasks might not\nexceeds 10 (at the pick next run time) - the idle tasks are excluded since they\nare dequeued when sleeping and enqueued when they wake up.\n\n## Tasks' Priorities\nThe priorities are applied as the followings:\nThe `vruntime` is used in Interactivity Score as the sum of execution time. The `vruntime` is adjusted by CFS based on tasks priorities.\nThe same code from CFS is used in CacULE. The `vruntime` is equal to `sum_exec_runtime` if a task has nice value of 0 (normal priority).\nThe `vruntime` will be lower than `sum_exec_runtime` for higher tasks priorities, which make Interactivity Score thinks that those task didn't run for much time (compared to\ntheir actual run time).\nThe `vruntime` will be higher than `sum_exec_runtime` for lower tasks priorities, which make Interactivity Score thinks that those task ran for much time (compared to\ntheir actual run time).\nSo priorities are already taken in the acount by using `vruntime` in the Interactivity Score equation instead of actual `sum_exec_runtime`.\n\n\n## Response Driven Balancer (RDB)\nThis is an experimental load balancer for Cachy/CacULE. It is a lightweight\nload balancer which is a replacement of CFS load balancer. It migrates\ntasks based on their HRRN/Interactivity Scores (IS). Most of CFS load balancing-related\nupdates (cfs and se updates loads) are removed. The RDB balancer follows CFS\nparadigm in which RDB balancing happen at the same points CFS does. RDB balancing happens\nin three functions: `newidle_balance`, `idle_balance`, and `active_balance`. The `newidle_balance`\nis called exactly at the same time as CFS did (when pick next task fails to find any task to run).\nThe RDB `newidle_balance` pulls one task that is the highest HRRN/IS from any CPU. The RDB `idle_balance`\nis called in `trigger_load_balance` when CPU is idle, it does the same as `newidle_balance` but with \nslight changes since `newidle_balance` is a special case. The RDB `active_balance` checks if the current\n(NORMAL) runqueue has one task, if so, it pulls the highest of the highest HRRN/IS among all other CPUS. If the\nrunqueue has more than one task, then it pulls any highest HRRN/IS (same as idle does). A CPU cannot pull a task\nfrom another CPU that has fewer tasks (when pull any). For the all three balancing\n`newidle_balance`, `idle_balance`, and `active_balance`, the cpu first tries to pull from a CPU that shares the same\ncache (`cpus_share_cache`). If can't pull any then it tries to pull from any CPU even though they are not in the same core.\nOnly when pulling the highest of the highest HRRN/IS (i.e. `active_balance` when CPU has one task), there is no check for\nshared cache.\n\n## How to install\nThe following installation links are not only for easier installation,\nbut they are also right configured for best CacULE experience.\n\n### Debian/Ubuntu\n[XanMod](https://xanmod.org/)\n\n### Arch\n[AUR - ptr1337](https://aur.archlinux.org/packages/?K=ptr1337\u0026SeB=m)\n\n## Patched Kernel Tree\n1. Go to [kernel tree repository](https://github.com/hamadmarri/linux) \n2. Select a tag version that starts with `cachy / cacule` (i.e `cachy-5.8-r6`)\n3. Download and compile\n\n## How to apply the patch\n1. Download the linux kernel (https://www.kernel.org/) that is same version as the patch\n (i.e if patch file name is cachy-5.7.6.patch, then download https://cdn.kernel.org/pub/linux/kernel/v5.x/linux-5.7.6.tar.xz)\n2. Unzip linux kernel\n3. Download cachy patch file and place it inside the just unzipped linux kernel folder\n4. cd linux-(version)\n5. patch -p1 \u003c cachy-5.7.6.patch (or git -am)\n6. To build the kernel you need to follow linux build kernel documentation and tutorials.\n\n\nTo confirm that CacULE is currently running:\n```\n\ndmesg | grep -i \"cacule cpu\"\n[    0.122999] CacULE CPU scheduler v5.9 by Hamad Al Marri.\n\n```\n\n## Suggested Configs\nFor a helper script to auto config use [this](https://github.com/hamadmarri/cacule-cpu-scheduler/blob/master/scripts/apply_suggested_configs.sh)\n\n## Benchmarks\nThe tests are ran 11 times and best 10 tests are picked.\nBetween each test, a sleep for 2 minutes such the following script:\n\n```\n for i in (seq 1 11); sleep 2m; \u003ctest command\u003e; end\n```\n\nFor the following tests, CacULE is patched on Ubuntu linux-lowlatency kernel source.\n\n[Benchmarks Data](https://github.com/hamadmarri/cacule-cpu-scheduler/tree/master/helper%20docs%20for%20kernel%20dev/benchmarking)\n\n### Stress-ng test\n![Benchmarks Data](./helper\u0026#32;docs\u0026#32;for\u0026#32;kernel\u0026#32;dev/benchmarking/stress-ng/cacule-vs-lowlatency-bogo-ops.png)\n![Benchmarks Data](./helper\u0026#32;docs\u0026#32;for\u0026#32;kernel\u0026#32;dev/benchmarking/stress-ng/cacule-vs-lowlatency-bogo-ops-per-sec.png)\n\n### Latency test\nPlease see the scripts for responsiveness/latency tests:\n[os-scheduler-responsiveness-test](https://github.com/hamadmarri/os-scheduler-responsiveness-test)\n\n![Benchmarks Data](./helper\u0026#32;docs\u0026#32;for\u0026#32;kernel\u0026#32;dev/benchmarking/responsive\u0026#32;script/cacule-vs-lowlatency-python.png)\n![Benchmarks Data](./helper\u0026#32;docs\u0026#32;for\u0026#32;kernel\u0026#32;dev/benchmarking/responsive\u0026#32;script/cacule-vs-lowlatency-go.png)\n\n\n\n## Blind Tests\nI made comparison between cfs and cachy on xanmod, for blind test\n\n* test1: https://youtu.be/DilwWlNbExg?t=14\n* test2: https://youtu.be/1S3OxLrcbGY?t=14\n* test3: https://youtu.be/HqaNGhThihA?t=38\n\nto reveal the which is which go back to time 0s on the video and see `uname -r` output\n\nNote: In one of the tests, the recorder seems to be freezes and lagging, I repeated this test twice, while testing system is not pausing but the recorder maybe freezing or lagging while recording.\n\n\n## Special Thanks to\n1. Alexandre Frade (the maintainer of [xanmod](https://github.com/xanmod))\n2. Raymond K. Zhao ([github](https://github.com/raykzhao))\n3. Peter Jung ([github](https://github.com/ptr1337))\n4. JohnyPeaN ([github](https://github.com/JohnyPeaN))\n\n## Contacts\nTelegram: https://t.me/cacule_sched\n\n## Discussions\nhttps://github.com/hamadmarri/cacule-cpu-scheduler/discussions\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhamadmarri%2Fcacule-cpu-scheduler","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhamadmarri%2Fcacule-cpu-scheduler","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhamadmarri%2Fcacule-cpu-scheduler/lists"}