1 /*****************************************************************************\ 2 * locks.h - definitions for semaphore functions for slurmctld (locks.c) 3 ***************************************************************************** 4 * Copyright (C) 2002 The Regents of the University of California. 5 * Produced at Lawrence Livermore National Laboratory (cf, DISCLAIMER). 6 * Written by Morris Jette <jette@llnl.gov>, Randy Sanchez <rsancez@llnl.gov> 7 * CODE-OCEC-09-009. All rights reserved. 8 * 9 * This file is part of Slurm, a resource management program. 10 * For details, see <https://slurm.schedmd.com/>. 11 * Please also read the included file: DISCLAIMER. 12 * 13 * Slurm is free software; you can redistribute it and/or modify it under 14 * the terms of the GNU General Public License as published by the Free 15 * Software Foundation; either version 2 of the License, or (at your option) 16 * any later version. 17 * 18 * In addition, as a special exception, the copyright holders give permission 19 * to link the code of portions of this program with the OpenSSL library under 20 * certain conditions as described in each individual source file, and 21 * distribute linked combinations including the two. You must obey the GNU 22 * General Public License in all respects for all of the code used other than 23 * OpenSSL. If you modify file(s) with this exception, you may extend this 24 * exception to your version of the file(s), but you are not obligated to do 25 * so. If you do not wish to do so, delete this exception statement from your 26 * version. If you delete this exception statement from all source files in 27 * the program, then also delete it here. 28 * 29 * Slurm is distributed in the hope that it will be useful, but WITHOUT ANY 30 * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS 31 * FOR A PARTICULAR PURPOSE. See the GNU General Public License for more 32 * details. 33 * 34 * You should have received a copy of the GNU General Public License along 35 * with Slurm; if not, write to the Free Software Foundation, Inc., 36 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. 37 \*****************************************************************************/ 38 39 /*****************************************************************************\ 40 * Read/write locks are implemented by the routines in this directory by using 41 * a set of three (3) UNIX semaphores to lock a resource. 42 * 43 * The set of three (3) semaphores represent a reader semaphore, 44 * a writer semaphore and a writers waiting semaphore. 45 * 46 * The reader semaphore indicates the number of readers that currently have a 47 * read lock on the resource. 48 * The writers semaphore indicates that a writer has the resource locked. 49 * The writers waiting semaphore indicates the number of writers waiting to 50 * lock the resource. 51 * 52 * Readers cannot lock the resource until there are no writers waiting for the 53 * resource and the resource is not locked by a writer. 54 * 55 * Writers cannot lock the resource if the resource is locked by other writers 56 * or if any readers have the resource locked. 57 * 58 * Writers will have priority in locking the resource over readers because 59 * of the writers waiting semaphore. The writers waiting semaphore is incremented 60 * by a writer that is waiting to lock the resource. A reader cannot lock 61 * the resource until there are no writers waiting to lock the resource and 62 * the resource is not locked by a writer. 63 * 64 * So, if the resource is locked by an unspecified number of readers, 65 * and a writer trys to lock the resource, then the writer will be blocked 66 * until all of the previous readers have unlocked the resource. But, 67 * just before the writer checked to see if there were any readers locking 68 * the resource, the writer incremented the writers waiting semaphore, 69 * indicating that there is now a writer waiting to lock the resource. 70 * In the mean time, if an unspecified number of readers try to lock the 71 * resource after a writer (or writers) has tried to lock the resource, 72 * those readers will be blocked until all writers have obtained the lock on 73 * the resource, used the resource and unlocked the resource. The subsequent 74 * unspecified number of readers are blocked because they are waiting for the 75 * number of writers waiting semaphore to become 0, meaning that there are no 76 * writers waiting to lock the resource. 77 * 78 * use init_locks() to initialize the locks then 79 * lock_slurmctld() and unlock_slurmctld() to get the ordering so as to 80 * prevent deadlock. The arguments indicate the lock type required for 81 * each entity (job, node, etc.) in a well defined order. 82 * For example: no lock on the config data structure, read lock on the job 83 * and node data structures, and write lock on the partition data structure 84 * would look like this: "{ NO_LOCK, READ_LOCK, READ_LOCK, WRITE_LOCK }" 85 * 86 * NOTE: When using lock_slurmctld() and assoc_mgr_lock(), always call 87 * lock_slurmctld() before calling assoc_mgr_lock() and then call 88 * assoc_mgr_unlock() before calling unlock_slurmctld(). 89 \*****************************************************************************/ 90 91 #ifndef _SLURMCTLD_LOCKS_H 92 #define _SLURMCTLD_LOCKS_H 93 94 #include <stdbool.h> 95 96 /* levels of locking required for each data structure */ 97 typedef enum { 98 NO_LOCK, 99 READ_LOCK, 100 WRITE_LOCK 101 } lock_level_t; 102 103 /* slurmctld specific data structures to lock via APIs */ 104 typedef struct { 105 lock_level_t conf; 106 lock_level_t job; 107 lock_level_t node; 108 lock_level_t part; 109 lock_level_t fed; 110 } slurmctld_lock_t; 111 112 typedef enum { 113 CONF_LOCK, 114 JOB_LOCK, 115 NODE_LOCK, 116 PART_LOCK, 117 FED_LOCK, 118 ENTITY_COUNT 119 } lock_datatype_t; 120 121 #ifndef NDEBUG 122 extern bool verify_lock(lock_datatype_t datatype, lock_level_t level); 123 #endif 124 125 /* init_locks - create locks used for slurmctld data structure access 126 * control */ 127 extern void init_locks ( void ); 128 129 /* lock_slurmctld - Issue the required lock requests in a well defined order */ 130 extern void lock_slurmctld (slurmctld_lock_t lock_levels); 131 132 /* unlock_slurmctld - Issue the required unlock requests in a well 133 * defined order */ 134 extern void unlock_slurmctld (slurmctld_lock_t lock_levels); 135 136 extern int report_locks_set(void); 137 138 /* un/lock semaphore used for saving state of slurmctld */ 139 extern void lock_state_files ( void ); 140 extern void unlock_state_files ( void ); 141 142 #endif 143