more

Author: wdeconinck

pluto/examples/mpl_pinned_allocator.F90

@@ -14,8 +14,17 @@ subroutine mpl_allocator_init(bytes)
     real(8), parameter :: GB = 1024**3 ! 1 GB in bytes
     call pluto%trace%enable() ! Just for this example to show the trace output of the resource,
                               ! can also be enabled by setting the environment variable PLUTO_TRACE=1
+
     mpl_resource = pluto%pinned_pool_resource()
+        ! This resource will manage a pool of pinned host memory, which is useful for efficient data transfer between host and device.
+        ! The resource will grow the pool as needed when allocations are made, but we can also reserve a certain amount of memory upfront
+        ! to ensure that it is available when needed and to potentially improve performance by reducing fragmentation.
+        ! NB: another implementation of a resource could easily be conceived, and registered by name, without having to change the rest of the code that uses it.
+        ! For example:
+        !    mpl_resource = pluto%get_registered_resource("my_custom_resource_using_buddy_allocator")
+
     mpl_allocator = pluto%make_allocator(mpl_resource)
+
     call mpl_allocator_print()
     call mpl_resource%reserve(bytes) ! reserve memory if the resource supports it, otherwise this is a no-op
     call mpl_allocator_print()
@@ -44,21 +53,50 @@ program main
     call mpl_allocator_init(1024**3) ! 1 GB
 end block
 
-! Example using mpl_allocator_mod
+! Example using mpl_allocator_mod, encapsulating pluto completely
 block
     use mpl_allocator_mod, only : mpl_allocator
     real(8), pointer :: array(:,:)
+
+    ! Allocation using shape, anonymous array
+    call mpl_allocator%allocate(array, shape=[10, 8])
+    call mpl_allocator%deallocate(array)
+
+    ! Allocation using bounds, anonymous array
     call mpl_allocator%allocate(array, lbounds=[0,0], ubounds=[10, 8])
     call mpl_allocator%deallocate(array)
+
+    ! label array for tracing
+    call mpl_allocator%allocate("mpl_array", array, lbounds=[0,0], ubounds=[10, 8])
+    call mpl_allocator%deallocate("mpl_array", array)
 end block
 
+! ------------------------------------------------------------------------------------------------------------------------
+! Further examples that also use the pluto_module. This indicates that we will be able to use the same allocators
+! in other contexts independent of MPL, and that the resource is registered globally so that it can be used in other
+! translation units without having to pass it around.
+
 ! Example using mpl_resource using pluto%allocate / pluto%deallocate
 block
     use pluto_module, only : pluto
     use mpl_allocator_mod, only : mpl_resource
     real(8), pointer :: array(:,:)
+
+    ! Allocation using shape, anonymous array
+    call pluto%allocate(array, shape=[10, 8], resource=mpl_resource)
+    call pluto%deallocate(array, resource=mpl_resource) ! IMPORTANT, must match the resource used for allocation
+
+    ! Allocation using bounds, anonymous array
     call pluto%allocate(array, lbounds=[0,0], ubounds=[10, 8], resource=mpl_resource)
     call pluto%deallocate(array, resource=mpl_resource) ! IMPORTANT, must match the resource used for allocation
+
+    ! label array for tracing
+    call pluto%allocate("mpl_array", array, lbounds=[0,0], ubounds=[10, 8], resource=mpl_resource)
+    call pluto%deallocate("mpl_array", array, resource=mpl_resource)
+
+    ! Using label externally
+    call pluto%set_label("mpl_array_2"); call pluto%allocate(array, lbounds=[0,0], ubounds=[10, 8], resource=mpl_resource); call pluto%unset_label()
+    call pluto%set_label("mpl_array_2"); call pluto%deallocate(array, resource=mpl_resource); call pluto%unset_label()
 end block
 
 ! Example independent of mpl_allocator_mod, using the resource name directly.
@@ -68,16 +106,29 @@ program main
     type(pluto_allocator) :: allocator    
     real(8), pointer :: array(:,:)
     allocator = pluto%make_allocator("MPL") ! This has been registered by name, now equivalent to using mpl_allocator
+
+    ! anonymous array
     call allocator%allocate(array, lbounds=[0,0], ubounds=[10, 8])
     call allocator%deallocate(array)
+
+    ! label array for tracing
+    call allocator%allocate("mpl_array", array, lbounds=[0,0], ubounds=[10, 8])
+    call allocator%deallocate("mpl_array", array)
 end block
 
 ! Example independent of mpl_allocator_mod, using the resource name directly.
 block
     use pluto_module, only : pluto
     real(8), pointer :: array(:,:)
+
+    ! anonymous array
     call pluto%allocate(array, lbounds=[0,0], ubounds=[10, 8], resource="MPL")
     call pluto%deallocate(array, resource="MPL") ! IMPORTANT, must match the resource used for allocation
+
+    ! label array for tracing
+    call pluto%allocate("mpl_array", array, lbounds=[0,0], ubounds=[10, 8], resource="MPL")
+    call pluto%deallocate("mpl_array", array, resource="MPL") ! IMPORTANT, must match the resource used for allocation
+
 end block
 
 ! Example independent of mpl_allocator_mod, modifying the default host allocator in a scope.
@@ -88,8 +139,14 @@ program main
     call pluto%host%set_default_resource("MPL") ! set the default host resource for this scope to "MPL"
     block
         real(8), pointer :: array(:,:)
+
+        ! anonymous array
         call pluto%host%allocate(array, lbounds=[0,0], ubounds=[10, 8]) ! will use the default resource for the host, which is now "MPL"
-        call pluto%host%deallocate(array)
+        call pluto%host%deallocate(array) ! will use the default resource for the host, which is now "MPL"
+
+        ! label array for tracing
+        call pluto%host%allocate("mpl_array", array, lbounds=[0,0], ubounds=[10, 8]) ! will use the default resource for the host, which is now "MPL"
+        call pluto%host%deallocate("mpl_array", array) ! will use the default resource for the host, which is now "MPL"
     end block
     call pluto%scope%pop() ! restore the previous default resource for the host
 end block
@@ -101,10 +158,14 @@ program main
     use mpl_allocator_mod, only : mpl_resource
     call pluto%scope%push()
     call pluto%host%set_default_resource(mpl_resource) ! set the default host resource for this scope to mpl_resource
-    block 
+    block
         real(8), pointer :: array(:,:)
         call pluto%host%allocate(array, shape=[10, 8]) ! will use the default resource for the host, which is now mpl_resource
-        call pluto%host%deallocate(array)
+        call pluto%host%deallocate(array) ! will use the default resource for the host, which is now mpl_resource
+
+        ! label array for tracing
+        call pluto%host%allocate("mpl_array", array, shape=[10, 8]) ! will use the default resource for the host, which is now "MPL"
+        call pluto%host%deallocate("mpl_array", array) ! will use the default resource for the host, which is now "MPL"
     end block
     call pluto%scope%pop() ! restore the previous default resource for the host
 end block

pluto/src/CMakeLists.txt

@@ -125,6 +125,8 @@ if (HAVE_FORTRAN)
       pluto_f/pluto_module_allocator.F90
       pluto_f/pluto_module_scope.F90
       pluto_f/pluto_module_trace.F90
+      pluto_f/pluto_module_host.F90
+      pluto_f/pluto_module_device.F90
       pluto_f/pluto_module.F90
     PRIVATE_LIBS pluto
     PUBLIC_INCLUDES $<BUILD_INTERFACE:${CMAKE_Fortran_MODULE_DIRECTORY}>