add example mpl_pinned_allocator

Author: wdeconinck

pluto/examples/mpl_pinned_allocator.F90

@@ -0,0 +1,112 @@
+module mpl_allocator_mod
+
+use pluto_module, only : pluto_allocator, pluto_memory_resource
+type(pluto_allocator), save :: mpl_allocator
+type(pluto_memory_resource), save :: mpl_resource
+
+contains
+subroutine mpl_allocator_init(bytes)
+    use pluto_module, only : pluto, pluto_memory_resource
+    use iso_fortran_env, only : output_unit
+    implicit none
+    integer, intent(in) :: bytes ! the amount of memory to reserve initially in the pool resource, in 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()
+    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()
+
+    call pluto%register_resource("MPL", mpl_resource) ! So that we can refer to it by name in the future
+
+end subroutine mpl_allocator_init
+
+subroutine mpl_allocator_print()
+    use iso_fortran_env, only : output_unit
+    implicit none
+    real(8), parameter :: GB = 1024**3 ! 1 GB in bytes
+    write(output_unit, '(A, F6.2, A, A, F6.2, A)') "mpl_allocator: capacity:", mpl_resource%capacity()/GB, "GB", &
+                         ",   allocated:", mpl_resource%size()/GB, "GB"
+end subroutine mpl_allocator_print
+
+end module
+
+program main
+implicit none
+
+! Initialise the mpl_allocator in a separate block to show that it can be done independently of the rest of the code,
+! and that the resource is registered globally.
+block
+    use mpl_allocator_mod, only : mpl_allocator_init
+    call mpl_allocator_init(1024**3) ! 1 GB
+end block
+
+! Example using mpl_allocator_mod
+block
+    use mpl_allocator_mod, only : mpl_allocator
+    real(8), pointer :: array(:,:)
+    call mpl_allocator%allocate(array, lbounds=[0,0], ubounds=[10, 8])
+    call mpl_allocator%deallocate(array)
+end block
+
+! 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(:,:)
+    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
+end block
+
+! Example independent of mpl_allocator_mod, using the resource name directly.
+! This also shows that the resource is registered globally and can be used in other translation units.
+block
+    use pluto_module, only : pluto, pluto_allocator
+    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
+    call allocator%allocate(array, lbounds=[0,0], ubounds=[10, 8])
+    call allocator%deallocate(array)
+end block
+
+! Example independent of mpl_allocator_mod, using the resource name directly.
+block
+    use pluto_module, only : pluto
+    real(8), pointer :: 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
+end block
+
+! Example independent of mpl_allocator_mod, modifying the default host allocator in a scope.
+! This is a convenient way to use the resource without having to pass it explicitly to every allocate/deallocate call.
+block
+    use pluto_module, only : pluto
+    call pluto%scope%push()
+    call pluto%host%set_default_resource("MPL") ! set the default host resource for this scope to "MPL"
+    block
+        real(8), pointer :: 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)
+    end block
+    call pluto%scope%pop() ! restore the previous default resource for the host
+end block
+
+! Example modifying the default host allocator in a scope.
+! This is a convenient way to use the resource without having to pass it explicitly to every allocate/deallocate call.
+block
+    use pluto_module, only : pluto
+    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 
+        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)
+    end block
+    call pluto%scope%pop() ! restore the previous default resource for the host
+end block
+
+end program