MemoryMappedFile.CreateNew Method

Definition

Namespace:

System.IO.MemoryMappedFiles

Assemblies:

netstandard.dll, System.IO.MemoryMappedFiles.dll

Creates a memory-mapped file in system memory.

Overloads

CreateNew(String, Int64)	Creates a memory-mapped file that has the specified capacity in system memory.
CreateNew(String, Int64, MemoryMappedFileAccess)	Creates a memory-mapped file that has the specified capacity and access type in system memory.
CreateNew(String, Int64, MemoryMappedFileAccess, MemoryMappedFileOptions, HandleInheritability)	Creates a memory-mapped file that has the specified name, capacity, access type, memory allocation options and inheritability.

CreateNew(String, Int64)

Source:

MemoryMappedFile.cs

Creates a memory-mapped file that has the specified capacity in system memory.

C#

public static System.IO.MemoryMappedFiles.MemoryMappedFile CreateNew(string? mapName, long capacity);

Parameters

mapName

String

A name to assign to the memory-mapped file, or null for a MemoryMappedFile that you do not intend to share across processes.

capacity

Int64

The maximum size, in bytes, to allocate to the memory-mapped file.

Returns

MemoryMappedFile

A memory-mapped file that has the specified name and capacity.

Exceptions

ArgumentException

mapName is an empty string.

ArgumentOutOfRangeException

capacity is less than or equal to zero.

PlatformNotSupportedException

.NET Core and .NET 5+ only: Calls to the CreateNew method with a named memory mapped file (that is, a non-null mapName) are supported on Windows operating systems only.

Examples

The following example is composed of three separate processes (console applications) that write Boolean values to a memory-mapped file. The following sequence of actions occur:

1. Process A creates the memory-mapped file and writes a value to it.

2. Process B opens the memory-mapped file and writes a value to it.

3. Process C opens the memory-mapped file and writes a value to it.

4. Process A reads and displays the values from the memory-mapped file.

5. After Process A is finished with the memory-mapped file, the file is immediately reclaimed by garbage collection.

To run this example, do the following:

1. Compile the applications and open three Command windows.

2. In the first Command window, run Process A.

3. In the second Command window, run Process B.

4. Return to Process A and press ENTER.

5. In the third Command window, run Process C.

6. Return to Process A and press ENTER.

The output of Process A is as follows:

Start Process B and press ENTER to continue.
Start Process C and press ENTER to continue.
Process A says: True
Process B says: False
Process C says: True

Process A

C#

using System;
using System.IO;
using System.IO.MemoryMappedFiles;
using System.Threading;

class Program
{
    // Process A:
    static void Main(string[] args)
    {
        using (MemoryMappedFile mmf = MemoryMappedFile.CreateNew("testmap", 10000))
        {
            bool mutexCreated;
            Mutex mutex = new Mutex(true, "testmapmutex", out mutexCreated);
            using (MemoryMappedViewStream stream = mmf.CreateViewStream())
            {
                BinaryWriter writer = new BinaryWriter(stream);
                writer.Write(1);
            }
            mutex.ReleaseMutex();

            Console.WriteLine("Start Process B and press ENTER to continue.");
            Console.ReadLine();

            Console.WriteLine("Start Process C and press ENTER to continue.");
            Console.ReadLine();

            mutex.WaitOne();
            using (MemoryMappedViewStream stream = mmf.CreateViewStream())
            {
                BinaryReader reader = new BinaryReader(stream);
                Console.WriteLine("Process A says: {0}", reader.ReadBoolean());
                Console.WriteLine("Process B says: {0}", reader.ReadBoolean());
                Console.WriteLine("Process C says: {0}", reader.ReadBoolean());
            }
            mutex.ReleaseMutex();
        }
    }
}

Process B

C#

using System;
using System.IO;
using System.IO.MemoryMappedFiles;
using System.Threading;

class Program
{
    // Process B:
    static void Main(string[] args)
    {
        try
        {
            using (MemoryMappedFile mmf = MemoryMappedFile.OpenExisting("testmap"))
            {

                Mutex mutex = Mutex.OpenExisting("testmapmutex");
                mutex.WaitOne();

                using (MemoryMappedViewStream stream = mmf.CreateViewStream(1, 0))
                {
                    BinaryWriter writer = new BinaryWriter(stream);
                    writer.Write(0);
                }
                mutex.ReleaseMutex();
            }
        }
        catch (FileNotFoundException)
        {
            Console.WriteLine("Memory-mapped file does not exist. Run Process A first.");
        }
    }
}

Process C

C#

using System;
using System.IO;
using System.IO.MemoryMappedFiles;
using System.Threading;

class Program
{
    // Process C:
    static void Main(string[] args)
    {
        try
        {
            using (MemoryMappedFile mmf = MemoryMappedFile.OpenExisting("testmap"))
            {

                Mutex mutex = Mutex.OpenExisting("testmapmutex");
                mutex.WaitOne();

                using (MemoryMappedViewStream stream = mmf.CreateViewStream(2, 0))
                {
                    BinaryWriter writer = new BinaryWriter(stream);
                    writer.Write(1);
                }
                mutex.ReleaseMutex();
            }
        }
        catch (FileNotFoundException)
        {
            Console.WriteLine("Memory-mapped file does not exist. Run Process A first, then B.");
        }
    }
}

Remarks

Use this method to create a memory-mapped file that is not persisted (that is, not associated with a file on disk), which you can use to share data between processes.

See also

• Memory-Mapped Files

CreateNew(String, Int64, MemoryMappedFileAccess)

Source:

MemoryMappedFile.cs

Creates a memory-mapped file that has the specified capacity and access type in system memory.

C#

public static System.IO.MemoryMappedFiles.MemoryMappedFile CreateNew(string? mapName, long capacity, System.IO.MemoryMappedFiles.MemoryMappedFileAccess access);

Parameters

mapName

String

A name to assign to the memory-mapped file, or null for a MemoryMappedFile that you do not intend to share across processes.

capacity

Int64

The maximum size, in bytes, to allocate to the memory-mapped file.

access

MemoryMappedFileAccess

One of the enumeration values that specifies the type of access allowed to the memory-mapped file. The default is ReadWrite.

Returns

MemoryMappedFile

A memory-mapped file that has the specified characteristics.

Exceptions

ArgumentException

mapName is an empty string.

-or-

access is set to write-only with the Write enumeration value.

ArgumentOutOfRangeException

capacity is less than or equal to zero.

-or-

access is not a valid MemoryMappedFileAccess enumeration value.

PlatformNotSupportedException

.NET Core and .NET 5+ only: Calls to the CreateNew method with a named memory mapped file (that is, a non-null mapName) are supported on Windows operating systems only.

Remarks

Use this method to create a memory-mapped file that is not persisted (that is, not associated with a file on disk), which you can use to share data between processes.

See also

• Memory-Mapped Files

CreateNew(String, Int64, MemoryMappedFileAccess, MemoryMappedFileOptions, HandleInheritability)

Source:

MemoryMappedFile.cs

Creates a memory-mapped file that has the specified name, capacity, access type, memory allocation options and inheritability.

C#

public static System.IO.MemoryMappedFiles.MemoryMappedFile CreateNew(string? mapName, long capacity, System.IO.MemoryMappedFiles.MemoryMappedFileAccess access, System.IO.MemoryMappedFiles.MemoryMappedFileOptions options, System.IO.HandleInheritability inheritability);

Parameters

mapName

String

A name to assign to the memory-mapped file, or null for a MemoryMappedFile that you do not intend to share across processes.

capacity

Int64

The maximum size, in bytes, to allocate to the memory-mapped file.

access

MemoryMappedFileAccess

One of the enumeration values that specifies the type of access allowed to the memory-mapped file. The default is ReadWrite.

options

MemoryMappedFileOptions

A bitwise combination of enumeration values that specifies memory allocation options for the memory-mapped file.

inheritability

HandleInheritability

A value that specifies whether a handle to the memory-mapped file can be inherited by a child process. The default is None.

Returns

MemoryMappedFile

A memory-mapped file that has the specified characteristics.

Exceptions

ArgumentException

mapName is an empty string.

-or-

access is set to write-only with the Write enumeration value.

ArgumentOutOfRangeException

capacity is less than or equal to zero.

-or-

access is not a valid MemoryMappedFileAccess enumeration value.

-or-

inheritability is not a valid HandleInheritability value.

PlatformNotSupportedException

.NET Core and .NET 5+ only: Calls to the CreateNew method with a named memory mapped file (that is, a non-null mapName) are supported on Windows operating systems only.