/** \file shared_memory.h
 * Here we define the interface for the shared memory interactions. This is
 * done to create a common interface for shared memory access for both POSIX
 * shared memory objects and Windows virtual file mappings.
 */

#ifndef _SHARED_MEMORY_H_
#define _SHARED_MEMORY_H_

#ifdef WIN32
#else
#include <sys/shm.h>    /* for shmget etc */
#endif

#include "semaphore.h"

#ifdef WIN32
typedef HANDLE file_handle_t;
#else
typedef int file_handle_t;
#endif

/* This is the struct that will be sitting in the shared memory and will allow
 * synchronized access to the data. */
typedef struct
{
  /* The maximum amount of data we can fit into the data chunk. */
  size_t maximum_bytes;

  /* The number of bytes written on the last IO operation. */
  size_t bytes_written;
} memory_chunk_t;

/* This struct will be sitting in local memory and contain local unshared
 * memory file descriptors for accessing the shared memory. */
typedef struct
{
  memory_chunk_t* memory;
  file_handle_t file_handle;
  semaphore_t can_read;
  semaphore_t can_write;
  void* data;
  char* name;
} shared_memory_t;

/* Creates a named shared memory segment. The mem_name specifies the unique
 * memory segment name. The length parameter specifies how much data the
 * shared memory chunk should be able to store. The function returns 0 on
 * success and error codes on failure. One possible error is if the shared
 * object with the same name already exists. */
int sharedmem_create(shared_memory_t* mem, char* mem_name, size_t length);

/* Opens a named shared memory segment. Returns 0 on success and an error code
 * on failure, for example if the shared memory segment does not exist. */
int sharedmem_open(shared_memory_t* mem, char* name);

/* Performs a synrchronized write of at most length bytes from data to the
 * memory. Returns the number of bytes written. */
size_t sharedmem_write(shared_memory_t* mem, const void* data, size_t length);

/* Performs a synchronized read of at most length bytes from shared memory to
 * data. Returns the number of bytes read. */
size_t sharedmem_read(shared_memory_t* mem, void* data, size_t length);

/* Performs a non-blocking read of at most length bytes from shared memory to
 * data. Returns the number of bytes read. */
size_t sharedmem_read_nb(shared_memory_t* mem, void* data, size_t length);

/* Closes the shared memory segment. This means that the shared memory object
 * will not be usable by the current process. Other processes will still be
 * able to use it, however. */
int sharedmem_close(shared_memory_t* mem);

/* Unlinks the shared memory segment. No process will be able to use this
 * memory afterwards. */
int sharedmem_unlink(shared_memory_t* mem);

#endif/*_SHARED_MEMORY_H_*/