ubik: Document lock ordering

[openafs.git] / src / ubik / ubik.p.h

diff --git a/src/ubik/ubik.p.h b/src/ubik/ubik.p.h
index bafe9f1..1d0834f 100644 (file)
--- a/src/ubik/ubik.p.h
+++ b/src/ubik/ubik.p.h
@@ -195,6 +195,19 @@ extern int (*ubik_SRXSecurityProc) (void *, struct rx_securityClass **,
 extern void *ubik_SRXSecurityRock;
 extern int (*ubik_CheckRXSecurityProc) (void *, struct rx_call *);
 extern void *ubik_CheckRXSecurityRock;
+
+extern void ubik_SetClientSecurityProcs(int (*scproc)(void *,
+                                                     struct rx_securityClass **,
+                                                     afs_int32 *),
+                                       int (*checkproc) (void *),
+                                       void *rock);
+extern void ubik_SetServerSecurityProcs
+               (void (*buildproc) (void *,
+                                    struct rx_securityClass ***,
+                                    afs_int32 *),
+                 int (*checkproc) (void *, struct rx_call *),
+                 void *rock);
+
 /*\}*/
 
 /*
@@ -327,14 +340,100 @@ extern int ubik_amSyncSite;      /* sleep on this waiting to be sync site */
 extern struct ubik_stats {     /* random stats */
     afs_int32 escapes;
 } ubik_stats;
-extern afs_int32 ubik_epochTime;       /* time when this site started */
 extern afs_int32 urecovery_state;      /* sync site recovery process state */
 extern struct ubik_trans *ubik_currentTrans;   /* current trans */
-extern struct ubik_version ubik_dbVersion;     /* sync site's dbase version */
 extern afs_int32 ubik_debugFlag;       /* ubik debug flag */
 extern int ubikPrimaryAddrOnly;        /* use only primary address */
 
-/* this extern gives the sync site's db version, with epoch of 0 if none yet */
+/*
+ * Lock ordering
+ *
+ * Any of the locks may be acquired singly; when acquiring multiple locks, they
+ * should be acquired in the listed order:
+ *     application cache lock  (dbase->cache_lock)
+ *     database lock           DBHOLD/DBRELE
+ *     beacon lock             UBIK_BEACON_LOCK/UNLOCK
+ *     vote lock               UBIK_VOTE_LOCK/UNLOCK
+ *     version lock            UBIK_VERSION_LOCK/UNLOCK
+ *     server address lock     UBIK_ADDR_LOCK/UNLOCK
+ */
+
+/*!
+ * \brief Global beacon data.  All values are protected by beacon_lock
+ * This lock also protects some values in the ubik_server structures:
+ *     lastVoteTime
+ *     lastBeaconSent
+ *     lastVote
+ *     up
+ *     beaconSinceDown
+ */
+struct beacon_data {
+#ifdef AFS_PTHREAD_ENV
+    pthread_mutex_t beacon_lock;
+#endif
+    int ubik_amSyncSite;               /*!< flag telling if I'm sync site */
+    afs_int32 syncSiteUntil;           /*!< valid only if amSyncSite */
+};
+
+#define UBIK_BEACON_LOCK MUTEX_ENTER(&beacon_globals.beacon_lock)
+#define UBIK_BEACON_UNLOCK MUTEX_EXIT(&beacon_globals.beacon_lock)
+
+/*!
+ * \brief Global vote data.  All values are protected by vote_lock
+ */
+struct vote_data {
+#ifdef AFS_PTHREAD_ENV
+    pthread_mutex_t vote_lock;
+#endif
+    struct ubik_version ubik_dbVersion;        /* sync site's dbase version */
+    struct ubik_tid ubik_dbTid;                /* sync site's tid, or 0 if none */
+    /* Used by all sites in nominating new sync sites */
+    afs_int32 ubik_lastYesTime;                /* time we sent the last yes vote */
+    afs_uint32 lastYesHost;            /* host to which we sent yes vote */
+    /* Next is time sync site began this vote: guarantees sync site until this + SMALLTIME */
+    afs_int32 lastYesClaim;
+    int lastYesState;                  /* did last site we voted for claim to be sync site? */
+    /* Used to guarantee that nomination process doesn't loop */
+    afs_int32 lowestTime;
+    afs_uint32 lowestHost;
+    afs_int32 syncTime;
+    afs_int32 syncHost;
+};
+
+#define UBIK_VOTE_LOCK MUTEX_ENTER(&vote_globals.vote_lock)
+#define UBIK_VOTE_UNLOCK MUTEX_EXIT(&vote_globals.vote_lock)
+
+/*!
+ * \brief Server address data.  All values are protected by addr_lock
+ *
+ * This lock also protects:
+ *     ubik_server: addr[], vote_rxcid, disk_rxcid
+ *
+ */
+struct addr_data {
+#ifdef AFS_PTHREAD_ENV
+    pthread_mutex_t addr_lock;
+#endif
+    afs_int32 ubikSecIndex;
+    struct rx_securityClass *ubikSecClass;
+};
+
+#define UBIK_ADDR_LOCK MUTEX_ENTER(&addr_globals.addr_lock)
+#define UBIK_ADDR_UNLOCK MUTEX_EXIT(&addr_globals.addr_lock)
+
+/*!
+ * \brief The version lock protects the structure member, as well as
+ * the database version, flags, tidCounter, writeTidCounter
+ */
+struct version_data {
+#ifdef AFS_PTHREAD_ENV
+    pthread_mutex_t version_lock;
+#endif
+    afs_int32 ubik_epochTime;  /* time when this site started */
+};
+
+#define UBIK_VERSION_LOCK MUTEX_ENTER(&version_globals.version_lock)
+#define UBIK_VERSION_UNLOCK MUTEX_EXIT(&version_globals.version_lock)
 
 /* phys.c */
 extern int uphys_stat(struct ubik_dbase *adbase, afs_int32 afid,
@@ -403,6 +502,9 @@ extern void panic(char *format, ...)
     AFS_ATTRIBUTE_FORMAT(__printf__, 1, 2);
 
 extern afs_uint32 ubikGetPrimaryInterfaceAddr(afs_uint32 addr);
+
+extern int ubik_CheckAuth(struct rx_call *);
+
 /*\}*/
 
 /*! \name beacon.c */
@@ -416,6 +518,9 @@ extern int ubeacon_InitServerListByInfo(afs_uint32 ame,
                                        char clones[]);
 extern int ubeacon_InitServerList(afs_uint32 ame, afs_uint32 aservers[]);
 extern void *ubeacon_Interact(void *);
+extern struct beacon_data beacon_globals;
+extern struct addr_data addr_globals;
+
 /*\}*/
 
 /*! \name disk.c */
@@ -457,6 +562,9 @@ extern void ubik_dprint(const char *format, ...)
 
 extern void ubik_dprint_25(const char *format, ...)
     AFS_ATTRIBUTE_FORMAT(__printf__, 1, 2);
+extern struct vote_data vote_globals;
+extern void uvote_set_dbVersion(struct ubik_version);
+extern int uvote_eq_dbVersion(struct ubik_version);
 /*\}*/
 
 #endif /* UBIK_INTERNALS */
@@ -507,6 +615,7 @@ extern int ubik_GetVersion(struct ubik_trans *atrans,
 extern int ubik_CheckCache(struct ubik_trans *atrans,
                            ubik_updatecache_func check,
                            void *rock);
+extern struct version_data version_globals;
 /*\}*/
 
 /*! \name ubikclient.c */