Shared (interprocess) mutexes on Linux

README.md

shared_mutex

Microlibrary for inter-process mutexes on Linux.

Example which says it all

#include "shared_mutex.h"
#include <stdio.h>

int main() {
  // Init shared mutex by a name, which can be used by
  // any other process to access the mutex.
  // This function both creates new and opens an existing mutex.
  shared_mutex_t mutex = shared_mutex_init("/my-mutex");
  if (mutex.ptr == NULL) {
    return 1;
  }

  if (mutex.created) {
    printf("The mutex was just created\n");
  }

  // Use pthread calls for locking and unlocking.
  pthread_mutex_lock(mutex.ptr);
  printf("Press eny key to unlock the mutex");
  getchar();
  pthread_mutex_unlock(mutex.ptr);

  // Closing is used to release local resources, used by a mutex.
  // It's still available to any other process.
  if (shared_mutex_close(mutex)) {
    return 1;
  }
  return 0;
}

int cleanup() {
  // Mutex destruction completely cleans it from system memory.
  if (shared_mutex_destroy(mutex)) {
    return 1;
  }
  return 0;
}

Usage

• Download shared_mutex.h and shared_mutex.c into your project.
• Building requires linking with pthread and librt.

Docs

shared_mutex_t

Structure of a shared mutex.

typedef struct shared_mutex_t {
  pthread_mutex_t *ptr; // Pointer to the pthread mutex and
                        // shared memory segment.
  int shm_fd;           // Descriptor of shared memory object.
  char* name;           // Name of the mutex and associated
                        // shared memory object.
  int created;          // Equals 1 (true) if initialization
                        // of this structure caused creation
                        // of a new shared mutex.
                        // Equals 0 (false) if this mutex was
                        // just retrieved from shared memory.
} shared_mutex_t;

shared_mutex_init

shared_mutex_t shared_mutex_init(char *name);

Initialize a new shared mutex with given name. If a mutex with such name exists in the system, it will be loaded. Otherwise a new mutes will by created.

In case of any error, it will be printed into the standard output and the returned structure will have ptr equal NULL. errno wil not be reset in such case, so you may used it.

NOTE: In case when the mutex appears to be uncreated, this function becomes non-thread-safe. If multiple threads call it at one moment, there occur several race conditions, in which one call might recreate another's shared memory object or rewrite another's pthread mutex in the shared memory. There is no workaround currently, except to run first initialization only before multi-threaded or multi-process functionality.

shared_mutex_close

int shared_mutex_close(shared_mutex_t mutex);

Close access to the shared mutex and free all the resources, used by the structure.

Returns 0 in case of success. If any error occurs, it will be printed into the standard output and the function will return -1. errno wil not be reset in such case, so you may used it.

NOTE: It will not destroy the mutex. The mutex would not only be available to other processes using it right now, but also to any process which might want to use it later on. For complete desctruction use shared_mutex_destroy instead.

NOTE: It will not unlock locked mutex.

shared_mutex_destroy

int shared_mutex_destroy(shared_mutex_t mutex);

Close and destroy shared mutex. Any open pointers to it will be invalidated.

Returns 0 in case of success. If any error occurs, it will be printed into the standard output and the function will return -1. errno wil not be reset in such case, so you may used it.

NOTE: It will not unlock locked mutex.

LICENSE

MIT License

Copyright (c) 2018 Oleg Yamnikov

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

shared_mutex.c

#include "shared_mutex.h"
#include <errno.h> // errno, ENOENT
#include <fcntl.h> // O_RDWR, O_CREATE
#include <linux/limits.h> // NAME_MAX
#include <sys/mman.h> // shm_open, shm_unlink, mmap, munmap,
                      // PROT_READ, PROT_WRITE, MAP_SHARED, MAP_FAILED
#include <unistd.h> // ftruncate, close
#include <stdio.h> // perror
#include <stdlib.h> // malloc, free
#include <string.h> // strcpy

shared_mutex_t shared_mutex_init(char *name) {
  shared_mutex_t mutex = {NULL, 0, NULL, 0};
  errno = 0;

  // Open existing shared memory object, or create one.
  // Two separate calls are needed here, to mark fact of creation
  // for later initialization of pthread mutex.
  mutex.shm_fd = shm_open(name, O_RDWR, 0660);
  if (errno == ENOENT) {
    mutex.shm_fd = shm_open(name, O_RDWR|O_CREAT, 0660);
    mutex.created = 1;
  }
  if (mutex.shm_fd == -1) {
    perror("shm_open");
    return mutex;
  }

  // Truncate shared memory segment so it would contain
  // pthread_mutex_t.
  if (ftruncate(mutex.shm_fd, sizeof(pthread_mutex_t)) != 0) {
    perror("ftruncate");
    return mutex;
  }

  // Map pthread mutex into the shared memory.
  void *addr = mmap(
    NULL,
    sizeof(pthread_mutex_t),
    PROT_READ|PROT_WRITE,
    MAP_SHARED,
    mutex.shm_fd,
    0
  );
  if (addr == MAP_FAILED) {
    perror("mmap");
    return mutex;
  }
  pthread_mutex_t *mutex_ptr = (pthread_mutex_t *)addr;

  // If shared memory was just initialized -
  // initialize the mutex as well.
  if (mutex.created) {
    pthread_mutexattr_t attr;
    if (pthread_mutexattr_init(&attr)) {
      perror("pthread_mutexattr_init");
      return mutex;
    }
    if (pthread_mutexattr_setpshared(&attr, PTHREAD_PROCESS_SHARED)) {
      perror("pthread_mutexattr_setpshared");
      return mutex;
    }
    if (pthread_mutex_init(mutex_ptr, &attr)) {
      perror("pthread_mutex_init");
      return mutex;
    }
  }
  mutex.ptr = mutex_ptr;
  mutex.name = (char *)malloc(NAME_MAX+1);
  strcpy(mutex.name, name);
  return mutex;
}

int shared_mutex_close(shared_mutex_t mutex) {
  if (munmap((void *)mutex.ptr, sizeof(pthread_mutex_t))) {
    perror("munmap");
    return -1;
  }
  mutex.ptr = NULL;
  if (close(mutex.shm_fd)) {
    perror("close");
    return -1;
  }
  mutex.shm_fd = 0;
  free(mutex.name);
  return 0;
}

int shared_mutex_destroy(shared_mutex_t mutex) {
  if ((errno = pthread_mutex_destroy(mutex.ptr))) {
    perror("pthread_mutex_destroy");
    return -1;
  }
  if (munmap((void *)mutex.ptr, sizeof(pthread_mutex_t))) {
    perror("munmap");
    return -1;
  }
  mutex.ptr = NULL;
  if (close(mutex.shm_fd)) {
    perror("close");
    return -1;
  }
  mutex.shm_fd = 0;
  if (shm_unlink(mutex.name)) {
    perror("shm_unlink");
    return -1;
  }
  free(mutex.name);
  return 0;
}

shared_mutex.h

#ifndef SHARED_MUTEX_H
#define SHARED_MUTEX_H

#define _BSD_SOURCE // for ftruncate
#include <pthread.h> // pthread_mutex_t, pthread_mutexattr_t,
                     // pthread_mutexattr_init, pthread_mutexattr_setpshared,
                     // pthread_mutex_init, pthread_mutex_destroy

// Structure of a shared mutex.
typedef struct shared_mutex_t {
  pthread_mutex_t *ptr; // Pointer to the pthread mutex and
                        // shared memory segment.
  int shm_fd;           // Descriptor of shared memory object.
  char* name;           // Name of the mutex and associated
                        // shared memory object.
  int created;          // Equals 1 (true) if initialization
                        // of this structure caused creation
                        // of a new shared mutex.
                        // Equals 0 (false) if this mutex was
                        // just retrieved from shared memory.
} shared_mutex_t;

// Initialize a new shared mutex with given `name`. If a mutex
// with such name exists in the system, it will be loaded.
// Otherwise a new mutes will by created.
//
// In case of any error, it will be printed into the standard output
// and the returned structure will have `ptr` equal `NULL`.
// `errno` wil not be reset in such case, so you may used it.
//
// **NOTE:** In case when the mutex appears to be uncreated,
// this function becomes *non-thread-safe*. If multiple threads
// call it at one moment, there occur several race conditions,
// in which one call might recreate another's shared memory
// object or rewrite another's pthread mutex in the shared memory.
// There is no workaround currently, except to run first
// initialization only before multi-threaded or multi-process
// functionality.
shared_mutex_t shared_mutex_init(char *name);

// Close access to the shared mutex and free all the resources,
// used by the structure.
//
// Returns 0 in case of success. If any error occurs, it will be
// printed into the standard output and the function will return -1.
// `errno` wil not be reset in such case, so you may used it.
//
// **NOTE:** It will not destroy the mutex. The mutex would not
// only be available to other processes using it right now,
// but also to any process which might want to use it later on.
// For complete desctruction use `shared_mutex_destroy` instead.
//
// **NOTE:** It will not unlock locked mutex.
int shared_mutex_close(shared_mutex_t mutex);

// Close and destroy shared mutex.
// Any open pointers to it will be invalidated.
//
// Returns 0 in case of success. If any error occurs, it will be
// printed into the standard output and the function will return -1.
// `errno` wil not be reset in such case, so you may used it.
//
// **NOTE:** It will not unlock locked mutex.
int shared_mutex_destroy(shared_mutex_t mutex);

#endif // SHARED_MUTEX_H

Thank you very much for this wrapper.

I have forked this and fixed some compiler warnings.

I also added a call to fchmod to properly set permissions on shm_open. Otherwise there is an implicit ~ 022 based on your umask and the files created in /dev/shm do not have the proper permissions for sharing that memory across users.

It'd rather do shm_open(name, O_RDWR|O_CREAT|O_EXCL, 0660); The check for the existence shall be atomic. Is it right?

@kujablik Yes, you must be right. Unfortunately I can't test and commit the fix right now: haven't worked with C for a while, it would take some time to set up the environment and re-learn the practices :)

Is it not possible to implement named mutex using the named semaphore provided already by pthread?

Can implement shared_cond by simple replace with pthread condition variable?

According to https://linux.die.net/man/3/shm_open a call to shm_open(...,O_CREAT|O_EXCL...) should fail with EEXIST if the object already exists. So, should one reorder the check during initialization, that is, first try to create the object atomically via O_CREAT|O_EXCL and then check for EEXIST to open the already existing object? This would make a inter-process race condition where multiple processes initialize the object at the same time less likely, I think.

@david-sackstein In theory yes, but you would need a process-shared condition variable too to avoid busy-waiting effectively.

It is a good idea to also do pthread_mutexattr_setrobust(&attr, PTHREAD_MUTEX_ROBUST), not to lock forever the mutex if the owner crashes.
It is also good to add a shared_mutex_lock function that handles the EOWNERDEAD return code, and also makes the shared_mutex_t opaque.

int shared_mutex_lock(const shared_mutex_t* mutex)
{
	int result = pthread_mutex_lock(mutex->ptr);
	if (result == EOWNERDEAD)
	{
		result = pthread_mutex_consistent(mutex->ptr);
		if (result != 0)
			perror("pthread_mutex_consistent");
	}
	
	return result;
}

int shared_mutex_unlock(const shared_mutex_t* mutex)
{
	return pthread_mutex_unlock(mutex->ptr);
}

You can simply use named semaphores for inter-process synchronization.
See: https://man7.org/linux/man-pages/man7/sem_overview.7.html

Unfortunately, named semaphore remains locked after process death, so the robust mutex is one of viable alternatives.