lazyfork 0.0.1__tar.gz

lazyfork-0.0.1/.gitignore

@@ -0,0 +1,5 @@
+.agent/
+temp/
+
+# Python
+**/__pycache__/

lazyfork-0.0.1/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

lazyfork-0.0.1/PKG-INFO

@@ -0,0 +1,214 @@
+Metadata-Version: 2.5
+Name: lazyfork
+Version: 0.0.1
+Summary: Fork a running containerised runtime N ways via CRIU lazy restore
+License:                                  Apache License
+                                   Version 2.0, January 2004
+                                http://www.apache.org/licenses/
+        
+           TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+        
+           1. Definitions.
+        
+              "License" shall mean the terms and conditions for use, reproduction,
+              and distribution as defined by Sections 1 through 9 of this document.
+        
+              "Licensor" shall mean the copyright owner or entity authorized by
+              the copyright owner that is granting the License.
+        
+              "Legal Entity" shall mean the union of the acting entity and all
+              other entities that control, are controlled by, or are under common
+              control with that entity. For the purposes of this definition,
+              "control" means (i) the power, direct or indirect, to cause the
+              direction or management of such entity, whether by contract or
+              otherwise, or (ii) ownership of fifty percent (50%) or more of the
+              outstanding shares, or (iii) beneficial ownership of such entity.
+        
+              "You" (or "Your") shall mean an individual or Legal Entity
+              exercising permissions granted by this License.
+        
+              "Source" form shall mean the preferred form for making modifications,
+              including but not limited to software source code, documentation
+              source, and configuration files.
+        
+              "Object" form shall mean any form resulting from mechanical
+              transformation or translation of a Source form, including but
+              not limited to compiled object code, generated documentation,
+              and conversions to other media types.
+        
+              "Work" shall mean the work of authorship, whether in Source or
+              Object form, made available under the License, as indicated by a
+              copyright notice that is included in or attached to the work
+              (an example is provided in the Appendix below).
+        
+              "Derivative Works" shall mean any work, whether in Source or Object
+              form, that is based on (or derived from) the Work and for which the
+              editorial revisions, annotations, elaborations, or other modifications
+              represent, as a whole, an original work of authorship. For the purposes
+              of this License, Derivative Works shall not include works that remain
+              separable from, or merely link (or bind by name) to the interfaces of,
+              the Work and Derivative Works thereof.
+        
+              "Contribution" shall mean any work of authorship, including
+              the original version of the Work and any modifications or additions
+              to that Work or Derivative Works thereof, that is intentionally
+              submitted to Licensor for inclusion in the Work by the copyright owner
+              or by an individual or Legal Entity authorized to submit on behalf of
+              the copyright owner. For the purposes of this definition, "submitted"
+              means any form of electronic, verbal, or written communication sent
+              to the Licensor or its representatives, including but not limited to
+              communication on electronic mailing lists, source code control systems,
+              and issue tracking systems that are managed by, or on behalf of, the
+              Licensor for the purpose of discussing and improving the Work, but
+              excluding communication that is conspicuously marked or otherwise
+              designated in writing by the copyright owner as "Not a Contribution."
+        
+              "Contributor" shall mean Licensor and any individual or Legal Entity
+              on behalf of whom a Contribution has been received by Licensor and
+              subsequently incorporated within the Work.
+        
+           2. Grant of Copyright License. Subject to the terms and conditions of
+              this License, each Contributor hereby grants to You a perpetual,
+              worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+              copyright license to reproduce, prepare Derivative Works of,
+              publicly display, publicly perform, sublicense, and distribute the
+              Work and such Derivative Works in Source or Object form.
+        
+           3. Grant of Patent License. Subject to the terms and conditions of
+              this License, each Contributor hereby grants to You a perpetual,
+              worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+              (except as stated in this section) patent license to make, have made,
+              use, offer to sell, sell, import, and otherwise transfer the Work,
+              where such license applies only to those patent claims licensable
+              by such Contributor that are necessarily infringed by their
+              Contribution(s) alone or by combination of their Contribution(s)
+              with the Work to which such Contribution(s) was submitted. If You
+              institute patent litigation against any entity (including a
+              cross-claim or counterclaim in a lawsuit) alleging that the Work
+              or a Contribution incorporated within the Work constitutes direct
+              or contributory patent infringement, then any patent licenses
+              granted to You under this License for that Work shall terminate
+              as of the date such litigation is filed.
+        
+           4. Redistribution. You may reproduce and distribute copies of the
+              Work or Derivative Works thereof in any medium, with or without
+              modifications, and in Source or Object form, provided that You
+              meet the following conditions:
+        
+              (a) You must give any other recipients of the Work or
+                  Derivative Works a copy of this License; and
+        
+              (b) You must cause any modified files to carry prominent notices
+                  stating that You changed the files; and
+        
+              (c) You must retain, in the Source form of any Derivative Works
+                  that You distribute, all copyright, patent, trademark, and
+                  attribution notices from the Source form of the Work,
+                  excluding those notices that do not pertain to any part of
+                  the Derivative Works; and
+        
+              (d) If the Work includes a "NOTICE" text file as part of its
+                  distribution, then any Derivative Works that You distribute must
+                  include a readable copy of the attribution notices contained
+                  within such NOTICE file, excluding those notices that do not
+                  pertain to any part of the Derivative Works, in at least one
+                  of the following places: within a NOTICE text file distributed
+                  as part of the Derivative Works; within the Source form or
+                  documentation, if provided along with the Derivative Works; or,
+                  within a display generated by the Derivative Works, if and
+                  wherever such third-party notices normally appear. The contents
+                  of the NOTICE file are for informational purposes only and
+                  do not modify the License. You may add Your own attribution
+                  notices within Derivative Works that You distribute, alongside
+                  or as an addendum to the NOTICE text from the Work, provided
+                  that such additional attribution notices cannot be construed
+                  as modifying the License.
+        
+              You may add Your own copyright statement to Your modifications and
+              may provide additional or different license terms and conditions
+              for use, reproduction, or distribution of Your modifications, or
+              for any such Derivative Works as a whole, provided Your use,
+              reproduction, and distribution of the Work otherwise complies with
+              the conditions stated in this License.
+        
+           5. Submission of Contributions. Unless You explicitly state otherwise,
+              any Contribution intentionally submitted for inclusion in the Work
+              by You to the Licensor shall be under the terms and conditions of
+              this License, without any additional terms or conditions.
+              Notwithstanding the above, nothing herein shall supersede or modify
+              the terms of any separate license agreement you may have executed
+              with Licensor regarding such Contributions.
+        
+           6. Trademarks. This License does not grant permission to use the trade
+              names, trademarks, service marks, or product names of the Licensor,
+              except as required for reasonable and customary use in describing the
+              origin of the Work and reproducing the content of the NOTICE file.
+        
+           7. Disclaimer of Warranty. Unless required by applicable law or
+              agreed to in writing, Licensor provides the Work (and each
+              Contributor provides its Contributions) on an "AS IS" BASIS,
+              WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+              implied, including, without limitation, any warranties or conditions
+              of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+              PARTICULAR PURPOSE. You are solely responsible for determining the
+              appropriateness of using or redistributing the Work and assume any
+              risks associated with Your exercise of permissions under this License.
+        
+           8. Limitation of Liability. In no event and under no legal theory,
+              whether in tort (including negligence), contract, or otherwise,
+              unless required by applicable law (such as deliberate and grossly
+              negligent acts) or agreed to in writing, shall any Contributor be
+              liable to You for damages, including any direct, indirect, special,
+              incidental, or consequential damages of any character arising as a
+              result of this License or out of the use or inability to use the
+              Work (including but not limited to damages for loss of goodwill,
+              work stoppage, computer failure or malfunction, or any and all
+              other commercial damages or losses), even if such Contributor
+              has been advised of the possibility of such damages.
+        
+           9. Accepting Warranty or Additional Liability. While redistributing
+              the Work or Derivative Works thereof, You may choose to offer,
+              and charge a fee for, acceptance of support, warranty, indemnity,
+              or other liability obligations and/or rights consistent with this
+              License. However, in accepting such obligations, You may act only
+              on Your own behalf and on Your sole responsibility, not on behalf
+              of any other Contributor, and only if You agree to indemnify,
+              defend, and hold each Contributor harmless for any liability
+              incurred by, or claims asserted against, such Contributor by reason
+              of your accepting any such warranty or additional liability.
+        
+           END OF TERMS AND CONDITIONS
+        
+           APPENDIX: How to apply the Apache License to your work.
+        
+              To apply the Apache License to your work, attach the following
+              boilerplate notice, with the fields enclosed by brackets "[]"
+              replaced with your own identifying information. (Don't include
+              the brackets!)  The text should be enclosed in the appropriate
+              comment syntax for the file format. We also recommend that a
+              file or class name and description of purpose be included on the
+              same "printed page" as the copyright notice for easier
+              identification within third-party archives.
+        
+           Copyright [yyyy] [name of copyright owner]
+        
+           Licensed under the Apache License, Version 2.0 (the "License");
+           you may not use this file except in compliance with the License.
+           You may obtain a copy of the License at
+        
+               http://www.apache.org/licenses/LICENSE-2.0
+        
+           Unless required by applicable law or agreed to in writing, software
+           distributed under the License is distributed on an "AS IS" BASIS,
+           WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+           See the License for the specific language governing permissions and
+           limitations under the License.
+License-File: LICENSE
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# LazyFork
+
+Fork a running containerised agent runtime N ways, cheaply. A fork is an exact copy of the parent mid-execution, built from one CRIU dump and many lazy restores that share untouched pages through the page cache.
+
+Early development. The API is not stable yet.

lazyfork-0.0.1/README.md

@@ -0,0 +1,5 @@
+# LazyFork
+
+Fork a running containerised agent runtime N ways, cheaply. A fork is an exact copy of the parent mid-execution, built from one CRIU dump and many lazy restores that share untouched pages through the page cache.
+
+Early development. The API is not stable yet.

lazyfork-0.0.1/experiments/lazy_pages_server.py

@@ -0,0 +1,261 @@
+import ctypes
+import errno
+import fcntl
+import logging
+import mmap
+import os
+import select
+import socket
+import struct
+import threading
+from dataclasses import dataclass, field
+from pathlib import Path
+
+PAGE = 4096
+IMG_COMMON_MAGIC = 0x54564319
+PAGEMAP_MAGIC = 0x56084025
+RESTORE_FINISHED = 0x52535446
+PE_PRESENT = 1 << 2
+
+UFFD_EVENT_PAGEFAULT = 0x12
+UFFD_EVENT_FORK = 0x13
+UFFD_EVENT_REMAP = 0x14
+UFFD_EVENT_REMOVE = 0x15
+UFFD_EVENT_UNMAP = 0x16
+UFFDIO_COPY = 0xC028AA03
+UFFDIO_ZEROPAGE = 0xC020AA04
+UFFD_MSG_SIZE = 32
+
+log = logging.getLogger("uffd")
+
+
+def _varint(buf: bytes, pos: int) -> tuple[int, int]:
+    value = shift = 0
+    while True:
+        b = buf[pos]
+        pos += 1
+        value |= (b & 0x7F) << shift
+        if not b & 0x80:
+            return value, pos
+        shift += 7
+
+
+def _decode(buf: bytes) -> dict[int, int]:
+    fields: dict[int, int] = {}
+    pos = 0
+    while pos < len(buf):
+        tag, pos = _varint(buf, pos)
+        if tag & 7 != 0:
+            raise ValueError(f"unexpected wire type in tag {tag}")
+        fields[tag >> 3], pos = _varint(buf, pos)
+    return fields
+
+
+class PageImage:
+    def __init__(self, images: Path, pid: int) -> None:
+        pagemap = (images / f"pagemap-{pid}.img").read_bytes()
+        common, magic = struct.unpack_from("<II", pagemap, 0)
+        if (common, magic) != (IMG_COMMON_MAGIC, PAGEMAP_MAGIC):
+            raise ValueError(f"bad pagemap magic {common:#x} {magic:#x}")
+        entries = []
+        pos = 8
+        while pos < len(pagemap):
+            (size,) = struct.unpack_from("<I", pagemap, pos)
+            pos += 4
+            entries.append(_decode(pagemap[pos:pos + size]))
+            pos += size
+        pages_id = entries[0][1]
+        self.pages: dict[int, int] = {}
+        offset = 0
+        for e in entries[1:]:
+            vaddr, flags = e[1], e.get(4, 0)
+            nr = e.get(5, e.get(2, 0))
+            if not flags & PE_PRESENT:
+                continue
+            for i in range(nr):
+                self.pages[vaddr + i * PAGE] = offset
+                offset += PAGE
+        fd = os.open(images / f"pages-{pages_id}.img", os.O_RDONLY)
+        try:
+            self.map = mmap.mmap(fd, 0, flags=mmap.MAP_PRIVATE, prot=mmap.PROT_READ | mmap.PROT_WRITE)
+        finally:
+            os.close(fd)
+        self.base = ctypes.addressof(ctypes.c_char.from_buffer(self.map))
+
+
+@dataclass
+class Task:
+    uffd: int
+    pid: int
+    image: PageImage
+    pages: dict[int, int]
+    owns_pages: bool = False
+    faults: int = 0
+    copied: int = 0
+    zeroed: int = 0
+    alive: bool = True
+
+    def private_pages(self) -> dict[int, int]:
+        if not self.owns_pages:
+            self.pages = dict(self.pages)
+            self.owns_pages = True
+        return self.pages
+
+
+@dataclass
+class Client:
+    sock: socket.socket
+    finished: bool = False
+    tasks: list[Task] = field(default_factory=list)
+
+
+class LazyPagesServer:
+    def __init__(self, images: Path, workdir: Path) -> None:
+        self.images = images
+        self.socket_path = workdir / "lazy-pages.socket"
+        self.socket_path.unlink(missing_ok=True)
+        self.listener = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+        self.listener.bind(str(self.socket_path))
+        self.listener.listen(64)
+        self.epoll = select.epoll()
+        self.epoll.register(self.listener.fileno(), select.EPOLLIN)
+        self.stop_r, self.stop_w = os.pipe()
+        self.epoll.register(self.stop_r, select.EPOLLIN)
+        self.image_cache: dict[int, PageImage] = {}
+        self.clients: dict[int, Client] = {}
+        self.tasks: dict[int, Task] = {}
+        self.accepted: list[Client] = []
+        self.thread = threading.Thread(target=self._loop, name="lazy-pages", daemon=True)
+
+    def start(self) -> None:
+        self.thread.start()
+
+    def stop(self) -> None:
+        os.write(self.stop_w, b"x")
+        self.thread.join()
+        for t in self.tasks.values():
+            os.close(t.uffd)
+        for c in self.clients.values():
+            c.sock.close()
+        self.listener.close()
+        self.socket_path.unlink(missing_ok=True)
+
+    def _image(self, pid: int) -> PageImage:
+        if pid not in self.image_cache:
+            self.image_cache[pid] = PageImage(self.images, pid)
+        return self.image_cache[pid]
+
+    def _loop(self) -> None:
+        while True:
+            for fd, ev in self.epoll.poll():
+                if fd == self.stop_r:
+                    return
+                if fd == self.listener.fileno():
+                    self._accept()
+                elif fd in self.clients:
+                    self._client_event(self.clients[fd], ev)
+                elif fd in self.tasks:
+                    self._task_event(self.tasks[fd], ev)
+
+    def _accept(self) -> None:
+        sock, _ = self.listener.accept()
+        client = Client(sock)
+        self.clients[sock.fileno()] = client
+        self.accepted.append(client)
+        self.epoll.register(sock.fileno(), select.EPOLLIN)
+        log.debug("client %d connected", sock.fileno())
+
+    def _client_event(self, client: Client, ev: int) -> None:
+        sock = client.sock
+        head = sock.recv(4, socket.MSG_WAITALL) if ev & select.EPOLLIN else b""
+        if len(head) < 4:
+            self.epoll.unregister(sock.fileno())
+            del self.clients[sock.fileno()]
+            sock.close()
+            log.debug("client closed, finished=%s", client.finished)
+            return
+        (value,) = struct.unpack("<i", head)
+        if value == RESTORE_FINISHED:
+            client.finished = True
+            return
+        if value < 0:
+            log.debug("zombie pid %d", -value)
+            return
+        _, fds, _, _ = socket.recv_fds(sock, 1, 1)
+        image = self._image(value)
+        task = Task(fds[0], value, image, image.pages)
+        self.tasks[task.uffd] = task
+        client.tasks.append(task)
+        self.epoll.register(task.uffd, select.EPOLLIN)
+        log.debug("task pid %d uffd %d registered, %d pages in image", value, task.uffd, len(image.pages))
+
+    def _task_event(self, task: Task, ev: int) -> None:
+        if ev & select.EPOLLIN:
+            while True:
+                try:
+                    msg = os.read(task.uffd, UFFD_MSG_SIZE)
+                except BlockingIOError:
+                    break
+                except OSError as e:
+                    if e.errno != errno.EBADF:
+                        raise
+                    msg = b""
+                if len(msg) < UFFD_MSG_SIZE:
+                    self._task_exit(task)
+                    return
+                self._handle(task, msg)
+        if ev & (select.EPOLLHUP | select.EPOLLERR) and task.alive:
+            self._task_exit(task)
+
+    def _handle(self, task: Task, msg: bytes) -> None:
+        event = msg[0]
+        if event == UFFD_EVENT_PAGEFAULT:
+            address = struct.unpack_from("<Q", msg, 16)[0] & ~(PAGE - 1)
+            task.faults += 1
+            offset = task.pages.get(address)
+            if offset is None:
+                arg = bytearray(struct.pack("<QQQq", address, PAGE, 0, 0))
+                if self._ioctl(task, UFFDIO_ZEROPAGE, arg):
+                    task.zeroed += 1
+            else:
+                arg = bytearray(struct.pack("<QQQQq", address, task.image.base + offset, PAGE, 0, 0))
+                if self._ioctl(task, UFFDIO_COPY, arg):
+                    task.copied += 1
+        elif event in (UFFD_EVENT_REMOVE, UFFD_EVENT_UNMAP):
+            start, end = struct.unpack_from("<QQ", msg, 8)
+            pages = task.private_pages()
+            for addr in range(start, end, PAGE):
+                pages.pop(addr, None)
+        elif event == UFFD_EVENT_REMAP:
+            src, dst, length = struct.unpack_from("<QQQ", msg, 8)
+            pages = task.private_pages()
+            moved = {dst + (a - src): pages.pop(a) for a in list(pages) if src <= a < src + length}
+            pages.update(moved)
+        elif event == UFFD_EVENT_FORK:
+            (child_fd,) = struct.unpack_from("<I", msg, 8)
+            child = Task(child_fd, task.pid, task.image, dict(task.pages), owns_pages=True)
+            self.tasks[child_fd] = child
+            self.epoll.register(child_fd, select.EPOLLIN)
+            log.debug("fork: uffd %d -> child uffd %d", task.uffd, child_fd)
+        else:
+            raise RuntimeError(f"unexpected uffd event {event:#x}")
+
+    def _ioctl(self, task: Task, request: int, arg: bytearray) -> bool:
+        try:
+            fcntl.ioctl(task.uffd, request, arg, True)
+            return True
+        except OSError as e:
+            if e.errno in (errno.EEXIST, errno.EAGAIN):
+                return False
+            if e.errno in (errno.ESRCH, errno.ENOSPC):
+                self._task_exit(task)
+                return False
+            raise
+
+    def _task_exit(self, task: Task) -> None:
+        if not task.alive:
+            return
+        task.alive = False
+        self.epoll.unregister(task.uffd)
+        log.debug("task uffd %d exited: faults=%d copied=%d zeroed=%d",
+                  task.uffd, task.faults, task.copied, task.zeroed)

lazyfork-0.0.1/experiments/lazy_restore_sharing.py

@@ -0,0 +1,220 @@
+import argparse
+import logging
+import os
+import shutil
+import signal
+import subprocess
+import sys
+import time
+from dataclasses import dataclass
+from pathlib import Path
+
+from lazy_pages_server import LazyPagesServer, Task
+
+HEAP_MB = 256
+
+log = logging.getLogger("experiment")
+
+
+def template_process() -> None:
+    os.setsid()
+    heap = bytearray(HEAP_MB << 20)
+    for i in range(0, len(heap), 4096):
+        heap[i] = i // 4096 % 251
+    print("ready", flush=True)
+    counter = 0
+    while True:
+        time.sleep(1)
+        counter += 1
+        page = (counter * 7919) % (len(heap) // 4096)
+        print(f"tick={counter} page={page} byte={heap[page * 4096]}", flush=True)
+
+
+@dataclass
+class MemSample:
+    rss_kb: int
+    pss_kb: int
+    shared_clean_kb: int
+    private_dirty_kb: int
+    pte_kb: int
+
+    @classmethod
+    def of(cls, pid: int) -> "MemSample":
+        rollup = dict(_kv(Path(f"/proc/{pid}/smaps_rollup")))
+        status = dict(_kv(Path(f"/proc/{pid}/status")))
+        return cls(
+            rss_kb=rollup["Rss"],
+            pss_kb=rollup["Pss"],
+            shared_clean_kb=rollup["Shared_Clean"],
+            private_dirty_kb=rollup["Private_Dirty"],
+            pte_kb=status["VmPTE"],
+        )
+
+    def row(self) -> str:
+        return (
+            f"{self.rss_kb / 1024:8.1f} {self.pss_kb / 1024:8.1f} "
+            f"{self.shared_clean_kb / 1024:8.1f} {self.private_dirty_kb / 1024:8.1f} "
+            f"{self.pte_kb:6d}"
+        )
+
+
+def _kv(path: Path) -> list[tuple[str, int]]:
+    out = []
+    for line in path.read_text().splitlines():
+        key, _, rest = line.partition(":")
+        parts = rest.split()
+        if parts and parts[-1] == "kB":
+            out.append((key, int(parts[0])))
+    return out
+
+
+def _mem_available_kb() -> int:
+    return dict(_kv(Path("/proc/meminfo")))["MemAvailable"]
+
+
+@dataclass
+class Restore:
+    index: int
+    workdir: Path
+    pid: int
+    restore_s: float
+    initial: MemSample
+
+
+class Experiment:
+    def __init__(self, images: Path, work: Path, count: int, settle_s: float, daemon: str) -> None:
+        self.images = images
+        self.work = work
+        self.count = count
+        self.settle_s = settle_s
+        self.daemon = daemon
+        self.server: LazyPagesServer | None = None
+
+    def run(self) -> None:
+        log.info("resetting %s and %s", self.images, self.work)
+        self._reset_dirs()
+        if self.daemon == "shared":
+            shared = self.work / "shared"
+            shared.mkdir()
+            server = LazyPagesServer(self.images, shared)
+            server.start()
+            self.server = server
+            log.info("shared lazy-pages server listening on %s", server.socket_path)
+        log.info("launching template")
+        template_pid = self._launch_template()
+        log.info("template ready, host pid %d", template_pid)
+        before = MemSample.of(template_pid)
+        log.info("dumping (log: %s)", self.images / "dump.log")
+        dump_s = self._timed(
+            ["criu", "dump", "-t", str(template_pid), "-D", str(self.images),
+             "-v4", "-o", "dump.log"]
+        )
+        image_mb = sum(p.stat().st_size for p in self.images.iterdir()) / (1 << 20)
+        log.info("dump done in %.0f ms, image %.0f MB", dump_s * 1000, image_mb)
+        host_before_kb = _mem_available_kb()
+        restores = [self._restore(i) for i in range(self.count)]
+        log.info("settling %.0f s", self.settle_s)
+        time.sleep(self.settle_s)
+        settled = [MemSample.of(r.pid) for r in restores]
+        host_delta_mb = (host_before_kb - _mem_available_kb()) / 1024
+        log.info("sampled after settle")
+
+        print(f"template pid={template_pid}  dump={dump_s * 1000:.0f} ms  image={image_mb:.0f} MB  daemon={self.daemon}")
+        print(f"{'who':<22} {'restore':>8} {'rss':>8} {'pss':>8} {'shared':>8} {'privdty':>8} {'pte':>6} {'faults':>16}")
+        print(f"{'template (pre-dump)':<22} {'':>8} {before.row()}")
+        for r, s in zip(restores, settled):
+            print(f"{'fork ' + str(r.index) + ' t=0':<22} {r.restore_s * 1000:6.0f}ms {r.initial.row()}")
+            print(f"{'fork ' + str(r.index) + f' t={self.settle_s:.0f}s':<22} {'':>8} {s.row()} {self._faults(r.index):>16}")
+        print("units: MB except pte (kB); faults = served (copied/zeroed)")
+        print(f"host MemAvailable drop for {self.count} forks: {host_delta_mb:.1f} MB "
+              f"({host_delta_mb / self.count:.2f} MB per fork)")
+
+        log.info("killing forks %s", [r.pid for r in restores])
+        for r in restores:
+            os.kill(r.pid, signal.SIGKILL)
+        if self.server:
+            time.sleep(0.2)
+            self.server.stop()
+
+    def _faults(self, index: int) -> str:
+        if not self.server:
+            return "-"
+        task: Task = self.server.accepted[index].tasks[0]
+        return f"{task.faults} ({task.copied}/{task.zeroed})"
+
+    def _reset_dirs(self) -> None:
+        for d in (self.images, self.work):
+            shutil.rmtree(d, ignore_errors=True)
+            d.mkdir(parents=True)
+
+    def _launch_template(self) -> int:
+        log_path = self.work / "template.log"
+        proc = subprocess.Popen(
+            ["unshare", "--pid", "--fork", sys.executable, __file__, "--template"],
+            stdin=subprocess.DEVNULL, stdout=log_path.open("w"), stderr=subprocess.STDOUT,
+        )
+        log.info("unshare pid %d, waiting for ready in %s", proc.pid, log_path)
+        deadline = time.monotonic() + 60
+        while "ready" not in log_path.read_text():
+            if time.monotonic() > deadline or proc.poll() is not None:
+                raise RuntimeError(f"template did not become ready: {log_path.read_text()}")
+            time.sleep(0.1)
+        children = Path(f"/proc/{proc.pid}/task/{proc.pid}/children").read_text().split()
+        return int(children[0])
+
+    def _restore(self, index: int) -> Restore:
+        if self.server:
+            workdir = self.server.socket_path.parent
+        else:
+            workdir = self.work / f"w{index}"
+            workdir.mkdir()
+            log.info("fork %d: starting lazy-pages daemon (log: %s)", index, workdir / "lp.log")
+            daemon_s = self._timed(
+                ["criu", "lazy-pages", "-D", str(self.images), "-W", str(workdir),
+                 "--daemon", "-v4", "-o", "lp.log"]
+            )
+            log.info("fork %d: daemon started in %.0f ms", index, daemon_s * 1000)
+        restore_log = f"restore-{index}.log"
+        pidfile = workdir / f"pid-{index}"
+        log.info("fork %d: restoring (log: %s)", index, workdir / restore_log)
+        restore_s = self._timed(
+            ["criu", "restore", "-D", str(self.images), "-W", str(workdir), "--lazy-pages",
+             "--restore-detached", "--pidfile", str(pidfile), "-v4", "-o", restore_log]
+        )
+        pid = int(pidfile.read_text())
+        log.info("fork %d: restored pid %d in %.0f ms", index, pid, restore_s * 1000)
+        return Restore(index, workdir, pid, restore_s, MemSample.of(pid))
+
+    @staticmethod
+    def _timed(cmd: list[str]) -> float:
+        log.debug("running: %s", " ".join(cmd))
+        start = time.perf_counter()
+        subprocess.run(cmd, check=True)
+        return time.perf_counter() - start
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--template", action="store_true")
+    parser.add_argument("--images", type=Path, default=Path("/var/lib/lazyfork/images/lazy_restore_sharing"))
+    parser.add_argument("--work", type=Path, default=Path("/tmp/lazyfork/lazy_restore_sharing"))
+    parser.add_argument("-n", "--count", type=int, default=2)
+    parser.add_argument("--settle", type=float, default=10.0)
+    parser.add_argument("-v", "--verbose", action="store_true")
+    parser.add_argument("--daemon", choices=["shared", "stock"], default="shared")
+    args = parser.parse_args()
+    if args.template:
+        template_process()
+        return
+    logging.basicConfig(
+        level=logging.DEBUG if args.verbose else logging.INFO,
+        format="%(relativeCreated)8.0f ms  %(message)s",
+        stream=sys.stderr,
+    )
+    if os.geteuid() != 0:
+        sys.exit("run as root")
+    Experiment(args.images, args.work, args.count, args.settle, args.daemon).run()
+
+
+if __name__ == "__main__":
+    main()

lazyfork-0.0.1/pyproject.toml

@@ -0,0 +1,15 @@
+[project]
+name = "lazyfork"
+version = "0.0.1"
+description = "Fork a running containerised runtime N ways via CRIU lazy restore"
+readme = "README.md"
+requires-python = ">=3.12"
+license = { file = "LICENSE" }
+dependencies = []
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/lazyfork"]

lazyfork-0.0.1/src/lazyfork/images.py

@@ -0,0 +1,96 @@
+import json
+import logging
+import shutil
+import subprocess
+import sys
+from dataclasses import dataclass, asdict
+from pathlib import Path
+
+DEFAULT_STORE = Path("/var/lib/lazyfork/rootfs")
+
+log = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True)
+class ImageConfig:
+    ref: str
+    id: str
+    env: list[str]
+    entrypoint: list[str]
+    cmd: list[str]
+    workdir: str
+    user: str
+
+    @classmethod
+    def from_inspect(cls, ref: str, inspect: dict) -> "ImageConfig":
+        config = inspect["Config"]
+        return cls(
+            ref=ref,
+            id=inspect["Id"].removeprefix("sha256:"),
+            env=config.get("Env") or [],
+            entrypoint=config.get("Entrypoint") or [],
+            cmd=config.get("Cmd") or [],
+            workdir=config.get("WorkingDir") or "/",
+            user=config.get("User") or "root",
+        )
+
+    def command(self, override: list[str] | None = None) -> list[str]:
+        return self.entrypoint + (override if override is not None else self.cmd)
+
+    def environ(self) -> dict[str, str]:
+        return dict(item.split("=", 1) for item in self.env)
+
+
+class ImageStore:
+    def __init__(self, root: Path = DEFAULT_STORE) -> None:
+        self.root = root
+
+    def pull(self, ref: str) -> ImageConfig:
+        if not self._inspect(ref):
+            log.info("pulling %s", ref)
+            subprocess.run(["nerdctl", "pull", "--quiet", ref], check=True)
+        inspect = self._inspect(ref)
+        if not inspect:
+            raise RuntimeError(f"image {ref} not found after pull")
+        return ImageConfig.from_inspect(ref, inspect[0])
+
+    def rootfs(self, image: ImageConfig) -> Path:
+        target = self.root / image.id
+        if (target / "rootfs").is_dir():
+            return target / "rootfs"
+        log.info("flattening %s into %s", image.ref, target)
+        staging = self.root / f".{image.id}.tmp"
+        shutil.rmtree(staging, ignore_errors=True)
+        (staging / "rootfs").mkdir(parents=True)
+        container = subprocess.run(
+            ["nerdctl", "create", image.ref], check=True, capture_output=True, text=True
+        ).stdout.strip()
+        try:
+            export = subprocess.Popen(["nerdctl", "export", container], stdout=subprocess.PIPE)
+            subprocess.run(["tar", "-x", "-C", str(staging / "rootfs")], stdin=export.stdout, check=True)
+            if export.wait() != 0:
+                raise RuntimeError(f"nerdctl export failed for {image.ref}")
+        finally:
+            subprocess.run(["nerdctl", "rm", "-f", container], check=True, capture_output=True)
+        (staging / "config.json").write_text(json.dumps(asdict(image), indent=2))
+        staging.rename(target)
+        return target / "rootfs"
+
+    def _inspect(self, ref: str) -> list[dict]:
+        result = subprocess.run(
+            ["nerdctl", "image", "inspect", ref], capture_output=True, text=True
+        )
+        return json.loads(result.stdout) if result.returncode == 0 else []
+
+
+def main() -> None:
+    logging.basicConfig(level=logging.INFO, format="%(message)s", stream=sys.stderr)
+    store = ImageStore()
+    image = store.pull(sys.argv[1])
+    rootfs = store.rootfs(image)
+    print(json.dumps(asdict(image), indent=2))
+    print(rootfs)
+
+
+if __name__ == "__main__":
+    main()

lazyfork-0.0.1/vm/lazyfork.yaml

@@ -0,0 +1,37 @@
+# LazyFork development VM.
+# Create once:   limactl create --name=lazyfork vm/lazyfork.yaml
+# Start / stop:  limactl start lazyfork / limactl stop lazyfork
+# Status:        limactl list
+# Shell:         limactl shell lazyfork
+base: template://ubuntu-26.04
+
+vmType: vz
+cpus: 4
+memory: "8GiB"
+disk: "40GiB"
+
+mounts:
+  - location: "~"
+    writable: true
+
+# The daemon's unix socket, forwarded to the Mac so the CLI/SDK can reach it.
+portForwards:
+  - guestSocket: "/run/lazyfork.sock"
+    hostSocket: "{{.Dir}}/sock/lazyfork.sock"
+
+provision:
+  # Runs as root on every boot. 
+  - mode: system
+    script: |
+      #!/bin/bash
+      set -eux
+      # Disable transparent huge pages to avoid huge page faults.
+      echo never > /sys/kernel/mm/transparent_hugepage/enabled
+      # CRIU images live on tmpfs so restore-many reads from the page cache.
+      mkdir -p /var/lib/lazyfork/images
+      mountpoint -q /var/lib/lazyfork/images || mount -t tmpfs -o size=4G tmpfs /var/lib/lazyfork/images
+      if ! command -v criu >/dev/null; then
+        export DEBIAN_FRONTEND=noninteractive
+        apt-get update
+        apt-get install -y criu
+      fi