From ba58e4d8f0907785a99c6a36510339889bee7396 Mon Sep 17 00:00:00 2001 From: Stella Laurenzo Date: Mon, 26 Aug 2024 21:29:29 -0700 Subject: [PATCH] [shortfin] Add documentation on ownership and lifetime of the system hierarchy. --- libshortfin/src/shortfin/local/system.h | 37 +++++++++++++++++++++++-- 1 file changed, 34 insertions(+), 3 deletions(-) diff --git a/libshortfin/src/shortfin/local/system.h b/libshortfin/src/shortfin/local/system.h index 3a5bbfd86..cb5c70808 100644 --- a/libshortfin/src/shortfin/local/system.h +++ b/libshortfin/src/shortfin/local/system.h @@ -42,9 +42,40 @@ class SystemBuilder; // on some form of factory that constructs one to suit both the system being // executed on and any preferences on which resources should be accessible. // -// As the root of the hierarchy and the owner of numerous ancillary resources, -// we declare that System is always managed via a shared_ptr, as this -// simplifies many aspects of system management. +// Ownership +// --------- +// There are three levels of ownership, all rooted on the System: +// 1. System: The System class, all drivers, devices, workers, and executors. +// There will only ever be one (or a small number if doing something multi +// tenant), and all owning references to the System are via +// `std::shared_ptr`. Every object in the system must either be +// a managed child of the system or own a system reference. +// 2. Scope: Binds any number of devices to a coherent schedule, rooted on +// a Worker. Scopes are independent of the system and there are generally +// as many as needed logical concurrency in the application. Each scope +// holds a system reference by way of a `std::shared_ptr`. These +// are still heavy-weight objects mostly created at initialization time +// and are therefore managed held as a `std::shared_ptr` by anything +// that depends on them. +// 3. TimelineResource: Any resource in the system (i.e. buffer, +// synchronization, object, etc) will hold a unique TimelineResource. These +// are light-weight objects managed via intrusive reference counting by +// their contained `TimelineResource::Ref` class. Each `TimelineResource` +// maintains a `std::shared_ptr` back reference to its owning +// scope. +// +// Leaf objects can have any lifetime that they wish, so long as they maintain +// an appropriate ownership reference into the System hierarchy above. This +// includes any application managed objects like arrays, storage, processes, +// messages, queues, etc. +// +// Lifetime debug logging can be enabled via compiler defines: +// SHORTFIN_LOG_LIFETIMES=1 : Enables constructor/destructor and this pointer +// logging for the primary objects in the system hierarchy. +// SHORTFIN_IREE_LOG_RC=1 : Enables the application view of IREE object +// reference counting, showing steal/retain/release and the number of +// references the application holds for each object. Also will log any +// outstanding references when the System is deallocated. class SHORTFIN_API System : public std::enable_shared_from_this { public: System(iree_allocator_t host_allocator);