src/include/gnunet_lockmanager_service.h

   1 /*
   2      This file is part of GNUnet.
   3      (C) 2012 Christian Grothoff (and other contributing authors)
   4
   5      GNUnet is free software; you can redistribute it and/or modify
   6      it under the terms of the GNU General Public License as published
   7      by the Free Software Foundation; either version 2, or (at your
   8      option) any later version.
   9
  10      GNUnet is distributed in the hope that it will be useful, but
  11      WITHOUT ANY WARRANTY; without even the implied warranty of
  12      MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13      General Public License for more details.
  14
  15      You should have received a copy of the GNU General Public License
  16      along with GNUnet; see the file COPYING.  If not, write to the
  17      Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  18      Boston, MA 02111-1307, USA.
  19 */
  20
  21 /**
  22  * @file include/gnunet_lockmanager_service.h
  23  * @brief API for the lockmanger service
  24  * @author Sree Harsha Totakura
  25  */
  26
  27 #ifndef GNUNET_LOCKMANAGER_SERVICE_H
  28 #define GNUNET_LOCKMANAGER_SERVICE_H
  29
  30 #ifdef __cplusplus
  31 extern "C"
  32 {
  33 #if 0                           /* keep Emacsens' auto-indent happy */
  34 }
  35 #endif
  36 #endif
  37
  38 /**
  39  * Opaque handle for the lockmanager service
  40  */
  41 struct GNUNET_LOCKMANAGER_Handle;
  42
  43
  44 /**
  45  * Connect to the lockmanager service
  46  *
  47  * @param cfg the configuration to use
  48  *
  49  * @param domain_name the name of the locking domain. If the locking domain
  50  *          isn't existing in the service it will be created. Clients who want
  51  *          to share locks must use the same name for the locking domain
  52  *
  53  * @return upon success the handle to the service; NULL upon error
  54  */
  55 struct GNUNET_LOCKMANAGER_Handle *
  56 GNUNET_LOCKMANAGER_connect (const struct GNUNET_CONFIGURATION_Handle *cfg,
  57                             const char *domain_name);
  58
  59
  60 /**
  61  * Disconnect from the lockmanager service
  62  *
  63  * @param handle the handle to the lockmanager service
  64  */
  65 void
  66 GNUNET_LOCKMANAGER_disconnect (struct GNUNET_LOCKMANAGER_Handle *handle);
  67
  68
  69 /**
  70  * This callback will be called after a locking operation has been
  71  * attempted. This callback will not be called when the LockingRequest has been
  72  * cancelled.
  73  *
  74  * @param cls the closure from GNUNET_LOCKMANAGER_lock call
  75  * @param lock the lock for which has been locked successfully
  76  */
  77 typedef void (*GNUNET_LOCKMANAGER_CompletionCallback) (void *cls,
  78                                                        unsigned int lock);
  79
  80
  81 /**
  82  * Opaque handle to locking request
  83  */
  84 struct GNUNET_LOCKMANAGER_LockingRequest;
  85
  86
  87 /**
  88  * Tries to lock the given lock
  89  *
  90  * @param handle the handle to the lockmanager service
  91  * @param lock which lock to lock
  92  * @param completion_cb the callback to be called when locking is successful
  93  * @param completion_cb_cls the closure to the above callback
  94  *
  95  * @return the locking request handle for this request. It will be invalidated
  96  *           when completion_cb is called.
  97  */
  98 struct GNUNET_LOCKMANAGER_LockingRequest *
  99 GNUNET_LOCKMANAGER_try_lock (struct GNUNET_LOCKMANAGER_Handle *handle,
 100                              unsigned int lock,
 101                              GNUNET_LOCKMANAGER_CompletionCallback
 102                              completion_cb,
 103                              void *completion_cb_cls);
 104
 105
 106 /**
 107  * Function to cancel the locking request generated by
 108  * GNUNET_LOCKMANAGER_try_lock. This should be used on a LockingRequest before
 109  * the completion_cb for the associated lock is called.
 110  *
 111  * @param request the LockingRequest to cancel
 112  */
 113 void
 114 GNUNET_LOCKMANAGER_cancel_request (struct GNUNET_LOCKMANAGER_LockingRequest
 115                                    *request);
 116
 117
 118 /**
 119  * Unlocks a lock which was locked by us. It does nothing when called on a lock
 120  * which wasn't locked or was locked by someone else.
 121  *
 122  * @param handle the handle to the lockmanager service
 123  * @param lock which lock to unlock
 124  */
 125 void
 126 GNUNET_LOCKMANAGER_unlock (const struct GNUNET_LOCKMANAGER_Handle *handle,
 127                            unsigned int lock);
 128
 129
 130 #if 0                           /* keep Emacsens' auto-indent happy */
 131 {
 132 #endif
 133 #ifdef __cplusplus
 134 }
 135 #endif
 136
 137 /* ifndef GNUNET_LOCKMANAGER_SERVICE_H */
 138 #endif
 139 /* end of gnunet_lockmanager_service.h */