shm (Shared Memory)

Header: udo/shm.h

Table of contents (click to go)

Macros

Enums

Unions

Structs

1. udo_shm

2. udo_shm_create_info

3. udo_shm_data_info

Functions

1. udo_shm_create()

2. udo_shm_data_read()

3. udo_shm_data_write()

4. udo_shm_get_fd()

5. udo_shm_get_data()

6. udo_shm_get_data_size()

7. udo_shm_destroy()

8. udo_shm_sizeof()

API Documentation

udo_shm_proc (private)

Structure defining the udo_shm_proc

(UDO Shared Memory Process) context.

struct udo_shm_proc

udo_atomic_u32 *rd_fux;

udo_atomic_u32 *wr_fux;

udo_atomic_addr data;

size_t data_sz;

rd_fux

Pointer to a given process read futex

stored in front segment of shared memory.

wr_fux

Pointer to a given process write futex

stored in front segment of shared memory.

data

Pointer to an unsigned char storing location

within shared memory. This pointer is a

given processes shared memory segment

staring address.

data_sz

Stores the size of a given processes

shared memory segment.

udo_shm (private)

Structure defining the udo_shm

(UDO Shared Memory) context.

struct udo_shm

struct udo_log_error_struct err;

bool free;

int fd;

char shm_file[SHM_FILE_NAME_MAX];

void *data;

size_t data_sz;

struct udo_shm_proc procs[SHM_PROC_MAX];

err

Stores information about the error that occured

for the given context and may later be retrieved

by caller.

free

If structure allocated with calloc(3) member will be

set to true so that, we know to call free(3) when

destroying the context.

fd

Open file descriptor to POSIX shared memory.

shm_file

Name of the POSIX shared memory file starting with '/'.

data

Pointer to mmap(2) map’d shared memory data.

data_sz

Total size of the shared memory region mapped with mmap(2).

procs

An array storing the shared memory locations

of each processes futexes and data.

---

udo_shm_create_info

Structure passed to udo_shm_create() used

to define shared memory file name, shm size,

and process count.

struct udo_shm_create_info

const char *shm_file;

size_t shm_size;

uint32_t proc_count;

shm_file

Shared memory file name. Must start

with the character '/'.

shm_size

Size of shared memory.

proc_count

Amount of processes able to read and

write to and from the shared memory

block.

struct udo_shm *udo_shm_create(struct udo_shm *shm, const void *shm_info);

Creates POSIX shared memory and futexes.

Each process gets:

1. Read futex (initialized to locked)

2. Write futex (initialized to unlocked)

3. Segment within shared memory to store data

Shared Memory Block (3 Processes)

Data Stored	Offset In Bytes	Byte Size	Initial Value
Process Count	0	4	0
P1 Read Futex	4	4	1
P1 Write Futex	8	4	0
P2 Read Futex	12	4	1
P2 Write Futex	16	4	0
P3 Read Futex	20	4	1
P3 Write Futex	24	4	0
P1 Data Segment	28	Varies based upon shm_size	0
P2 Data Segment	Varies based upon shm_size	Varies based upon shm_size	0
P3 Data Segment	Varies based upon shm_size	Varies based upon shm_size	0

Param	Decription
shm	May be NULL or a pointer to a struct udo_shm. If NULL memory will be allocated and return to caller. If not NULL address passed will be used to store the newly created struct udo_shm context.
shm_info	Implementation uses a pointer to a struct udo_shm_create_info.

Returns:

on success: Pointer to a struct udo_shm

on failure: NULL

---

udo_shm_data_info

Structure defining what operations to perform

and data to retrieve during calls to

udo_shm_data_read() and udo_shm_data_write().

struct udo_shm_data_info

void *data;

size_t size;

uint32_t proc_index;

data

Pointer to a buffer that will either be used

to store shm data or write to shm data.

size

Size in bytes to read from or write to shared memory.

proc_index

Index of process to write data to or read data from.

udo_shm_data_read

int udo_shm_data_read(struct udo_shm *shm, const void *shm_info);

Reads data stored in shared memory at

caller defined offset and writes into

a caller defined buffer.

Param	Decription
shm	Pointer to a valid struct udo_shm.
shm_info	Must pass a pointer to a struct udo_shm_data_info.

Returns:

on success: 0

on failure: -1

udo_shm_data_write

int udo_shm_data_write(struct udo_shm *shm, const void *shm_info);

Write data stored in caller defined buffer

into shared memory at a caller defined

shared memory offset.

Param	Decription
shm	Pointer to a valid struct udo_shm.
shm_info	Must pass a pointer to a struct udo_shm_data_info.

Returns:

on success: 0

on failure: -1

---

udo_shm_get_fd

int udo_shm_get_fd(struct udo_shm *shm);

Returns file descriptor to the POSIX shared memory

created after call to udo_shm_create().

Param	Decription
shm	Pointer to a valid struct udo_shm.

Returns:

on success: File descriptor to POSIX shared memory

on failure: -1

---

udo_shm_get_data

void *udo_shm_get_data(struct udo_shm *shm, const uint32_t proc_index);

Returns starting address of a processes segment

in the mmap(2) map’d POSIX shared memory buffer

created after call to udo_shm_create().

Param	Decription
shm	Pointer to a valid struct udo_shm.
proc_index	Process index to acquire it’s shared memory segment starting address.

Returns:

on success: Pointer to processes SHM segment

on failure: NULL

---

udo_shm_get_data_size

size_t udo_shm_get_data_size(struct udo_shm *shm, const uint32_t proc_index);

Returns size of a given process POSIX shared

memory segment size created after call to

udo_shm_create().

Param	Decription
shm	Pointer to a valid struct udo_shm.
proc_index	Process index to acquire it’s shared memory segment starting address.

Returns:

on success: Size of processes SHM segment

on failure: (size_t)-1

---

udo_shm_destroy

void udo_shm_destroy(struct udo_shm *shm);

Frees any allocated memory and closes FD’s (if open) created after

udo_shm_create() call.

Param	Decription
shm	Pointer to a valid struct udo_shm.

---

udo_shm_get_sizeof

int udo_shm_get_sizeof(void);

Returns size of the internal structure. So,

if caller decides to allocate memory outside

of API interface they know the exact amount

of bytes.

Returns:

on success: sizeof(struct udo_shm)

on failure: sizeof(struct udo_shm)

---