From: Sree Harsha Totakura <totakura@in.tum.de>
Date: Wed, 25 Apr 2012 10:02:51 +0000 (+0000)
Subject: -added interface for lockmanager
X-Git-Tag: initial-import-from-subversion-38251~13785
X-Git-Url: https://git.librecmc.org/?a=commitdiff_plain;h=9c4f5c8f1b481103f871c20bb568ff7d1911cb10;p=oweals%2Fgnunet.git

-added interface for lockmanager
---

diff --git a/src/include/gnunet_lockmanager_service.h b/src/include/gnunet_lockmanager_service.h
new file mode 100644
index 000000000..f2952a742
--- /dev/null
+++ b/src/include/gnunet_lockmanager_service.h
@@ -0,0 +1,139 @@
+/*
+     This file is part of GNUnet.
+     (C) 2012 Christian Grothoff (and other contributing authors)
+
+     GNUnet is free software; you can redistribute it and/or modify
+     it under the terms of the GNU General Public License as published
+     by the Free Software Foundation; either version 2, or (at your
+     option) any later version.
+
+     GNUnet is distributed in the hope that it will be useful, but
+     WITHOUT ANY WARRANTY; without even the implied warranty of
+     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+     General Public License for more details.
+
+     You should have received a copy of the GNU General Public License
+     along with GNUnet; see the file COPYING.  If not, write to the
+     Free Software Foundation, Inc., 59 Temple Place - Suite 330,
+     Boston, MA 02111-1307, USA.
+*/
+
+/**
+ * @file include/gnunet_lockmanager_service.h
+ * @brief API for the lockmanger service
+ * @author Sree Harsha Totakura
+ */
+
+#ifndef GNUNET_LOCKMANAGER_SERVICE_H
+#define GNUNET_LOCKMANAGER_SERVICE_H
+
+#ifdef __cplusplus
+extern "C"
+{
+#if 0                           /* keep Emacsens' auto-indent happy */
+}
+#endif
+#endif
+
+/**
+ * Opaque handle for the lockmanager service
+ */
+struct GNUNET_LOCKMANAGER_Handle;
+
+
+/**
+ * Connect to the lockmanager service
+ *
+ * @param cfg the configuration to use
+ *
+ * @param domain_name the name of the locking domain. If the locking domain
+ *          isn't existing in the service it will be created. Clients who want
+ *          to share locks must use the same name for the locking domain
+ *
+ * @return upon success the handle to the service; NULL upon error
+ */
+struct GNUNET_LOCKMANAGER_Handle *
+GNUNET_LOCKMANAGER_connect (const struct GNUNET_CONFIGURATION_Handle *cfg,
+                            const char *domain_name);
+
+
+/**
+ * Disconnect from the lockmanager service
+ *
+ * @param handle the handle to the lockmanager service
+ */
+void
+GNUNET_LOCKMANAGER_disconnect (struct GNUNET_LOCKMANAGER_Handle *handle);
+
+
+/**
+ * This callback will be called after a locking operation has been
+ * attempted. This callback will not be called when the LockingRequest has been
+ * cancelled.
+ *
+ * @param cls the closure from GNUNET_LOCKMANAGER_lock call
+ * @param lock the lock for which has been locked successfully
+ */
+typedef void (*GNUNET_LOCKMANAGER_CompletionCallback) (void *cls,
+                                                       unsigned int lock);
+
+
+/**
+ * Opaque handle to locking request
+ */
+struct GNUNET_LOCKMANAGER_LockingRequest;
+
+
+/**
+ * Tries to lock the given lock
+ *
+ * @param handle the handle to the lockmanager service
+ * @param lock which lock to lock
+ * @param completion_cb the callback to be called when locking is successful
+ * @param completion_cb_cls the closure to the above callback
+ *
+ * @return the locking request handle for this request. It will be invalidated
+ *           when completion_cb is called.
+ */
+struct GNUNET_LOCKMANAGER_LockingRequest *
+GNUNET_LOCKMANAGER_try_lock (struct GNUNET_LOCKMANAGER_Handle *handle,
+                             unsigned int lock,
+                             GNUNET_LOCKMANAGER_CompletionCallback
+                             completion_cb,
+                             void *completion_cb_cls);
+
+
+/**
+ * Function to cancel the locking request generated by
+ * GNUNET_LOCKMANAGER_try_lock. This should be used on a LockingRequest before
+ * the completion_cb for the associated lock is called.
+ *
+ * @param request the LockingRequest to cancel
+ */
+void
+GNUNET_LOCKMANAGER_cancel_request (struct GNUNET_LOCKMANAGER_LockingRequest
+                                   *request);
+
+
+/**
+ * Unlocks a lock which was locked by us. It does nothing when called on a lock
+ * which wasn't locked or was locked by someone else.
+ *
+ * @param handle the handle to the lockmanager service
+ * @param lock which lock to unlock
+ */
+void
+GNUNET_LOCKMANAGER_unlock (const struct GNUNET_LOCKMANAGER_Handle *handle,
+                           unsigned int lock);
+
+
+#if 0                           /* keep Emacsens' auto-indent happy */
+{
+#endif
+#ifdef __cplusplus
+}
+#endif
+
+/* ifndef GNUNET_LOCKMANAGER_SERVICE_H */
+#endif
+/* end of gnunet_lockmanager_service.h */
diff --git a/src/lockmanager/README b/src/lockmanager/README
new file mode 100644
index 000000000..ef38e990c
--- /dev/null
+++ b/src/lockmanager/README
@@ -0,0 +1,10 @@
+The lockmanager service serves as a global locker for other gnunet
+programs. This service eliminates the need for programs to maintain their own
+checks upon a resource which should be protected from concurrent access.
+
+Locking is managed through locking-domains. A locking-domain is a string which
+uniquely identifies a group of locks. Locks are represented as unsigned
+integers. When a critical resource has to be protected against simulataneous
+access by 2 programs. Both of them should connect to the lockmanager using the
+same locking-domain and try to lock a lock. Since only one of them can acquire
+the lock the other will be denied locking until the other releases it.
\ No newline at end of file