Creating a shared memory segment

create_shared_memory()

Create a shared memory segment

SYNTAX

create_shared_memory(share_name, record_id| file_id, perms, options)

Create a shared memory segment. Shared memory enables the data stored in a record or file structure to be shared between two or more Sculptor programs running on the same computer. One program creates a shared memory segment, and all other programs that wish to access the segment link to it.

The file or record buffer and the shared memory segment are not the same physical memory. Sculptor associates the shared memory segment with the specified buffer, and functions are used to transfer values safely between the buffer and the shared memory segment.

share_name	The name of the shared memory segment. This is an alphanumeric value; valid characters are A-Z, a-z, 0-9 and the underscore ( _ ). On Microsoft Windows, the names of shared memory segments are system global, so the chosen name should be one that is likely to be unique to the application. On UNIX, Sculptor converts the name to a system key that is a 4-byte integer on most systems. See options for further details of the system key.
record_id | file_id	The identifier of the record structure (!record) or file (![o]file) whose data is to be shared. The shared memory segment will be created large enough to store all the fields in the record or file.
perms	The access permissions to grant. The possible values are defined in the standard include file $SCULPTOR/include/files.h with the prefix PERMS_. On UNIX all permission bits are valid. On Windows the group bits are ignored, and one of the following combinations should be used: PERMS_R Read permission for current user only PERMS_RRR Read permission for all users PERMS_RW Read and write permission for current user only PERMS_RWRWRW Read and write permission for all users
options	See the options table below.

options possible values:

SHM_USE_FTOK	Unix only option for the create_shared_memory() and link_shared_memory(). If not specified creates the system key from a simple hash of share_name. If options = SHM_USE_FTOK, the C library function ftok() is called to create the key. In this case the first character of share_name is used as the id char for ftok(), and the remaining text as the pathname of an existing file that must be accessible to the process. See the UNIX documentation of ftok() for more details.
SHM_PERSIST	Since Sculptor version 6.2.0 Windows: Create the shared memory backed with a real file (stored in $SCULPTOR/shmem/<sharename>), which will permit the shared memory to persist even if all the shared memory handles are released. UNIX: Flag the shared memory to not be removed on last client detach.
SHM_GLOBAL	Since Sculptor version 6.2.0 Windows only option for the create_shared_memory() and link_shared_memory(). By default the shared memory is created in the “Local\” namespace, this option permits to create the shared memory in the “Global\” namespace so that it can be shared between different sessions in a Windows Host. Note: This file mapping object created in the “Global\” namespace requires the SeCreateGlobalPrivilege privilege (the privilege is only needed in the creation not in the link). See Kernel object namespaces (MSDN link).

The return value from the function must be stored in an i4 type field. If the function was successful, the return value is non-zero and is used to identify this shared memory segment in calls to other shared memory functions.

A return value of zero means that the function failed. The error number is stored in sys.Errno. Normal reasons for failure:

1	Another program has already created the shared memory segment.
2	The system has run out of shared memory segments. This is unlikely.

A segment is released when the program that created it, and all programs that linked to it, have released it or exited. A segment can still be used by the programs that have linked to it even if it has been released by the program that created it.

Note: On Windows the shared memory is implemented using shared views on file mapping objects (backed by the system paging file when option SHM_PERSIST is not used). This file mapping object was created in the “Global\” namespace by default, but since Sculptor version 6.2.0 it is created in the “Local\” namespace. This has to be taken into account when mixing Sculptor versions in the same host (The SHM_GLOBAL option should be used with the newer versions to share memory with old version binaries).

The programs shmcreate.r and shmlink.r, located in $SCULPTOR/demo/misc, demonstrate shared memory functions.

---

EXAMPLE

!record Clients {
     fieldlist
}

!temp SMclient,,i4

     SMclient = create_shared_memory("shm_segjx", Clients, PERMS_RRR, 0)
     if (SMclient == 0) {
          error "Error creating shared memory segment: errno = " + tostr(sys.Errno)
          exit
     }

---

Shared memory functions
create_shared_memory()	Create a shared memory segment
link_shared_memory()	Link to an existing shared memory segment
read_shared_memory()	Read the current field values from shared memory into associated record buffer
write_shared_memory()	Write the current values from associated record buffer into shared memory
unlock_shared_memory()	Unlock a shared memory segment
unlink_shared_memory()	Unlink a program from a shared memory segment

---

RELATED TOPICS

Shared memory options in sculptor.h

create_msg_queue()

!record

![o]file