From 1ad64953c611a4f8bcb436bc269b7a85820e23c2 Mon Sep 17 00:00:00 2001
From: anserper <anserper>
Date: Tue, 15 Jul 2008 17:05:07 +0000
Subject: [PATCH] Branch HEAD b=14010 i=Mike Pershin (tappro) i=Andreas Dilger
(adilger)
Doxygen comments (the missing ones)
---
lustre/include/obd_class.h | 41 +++++++++++++
lustre/ldlm/ldlm_lock.c | 34 +++++++++++
lustre/llite/file.c | 118 +++++++++++++++++++++++++++++++++++++
lustre/lov/lov_obd.c | 40 +++++++++++++
lustre/osc/osc_request.c | 40 +++++++++++++
5 files changed, 273 insertions(+)
diff --git a/lustre/include/obd_class.h b/lustre/include/obd_class.h
index d734870665..324fa1f53f 100644
--- a/lustre/include/obd_class.h
+++ b/lustre/include/obd_class.h
@@ -1212,6 +1212,29 @@ static inline int obd_prep_async_page(struct obd_export *exp,
RETURN(ret);
}
+/**
+ * Checks if requested extent lock is compatible with a lock under the page.
+ *
+ * Checks if the lock under \a page is compatible with a read or write lock
+ * (specified by \a rw) for an extent [\a start , \a end].
+ *
+ * \param exp obd export (lov or osc)
+ * \param lsm striping information for the file
+ * \param res async_page placeholder
+ * \param rw OBD_BRW_READ if requested for reading,
+ * OBD_BRW_WRITE if requested for writing
+ * \param start start of the requested extent
+ * \param end end of the requested extent
+ * \param cookie transparent parameter for passing locking context
+ *
+ * \post result == 1, *cookie == context, appropriate lock is referenced or
+ *
+ * \retval 1 owned lock is reused for the request
+ * \retval 0 no lock reused for the request
+ * \retval -ENOTSUPP reget_short_lock is not exported at this layer
+ *
+ * \see obd_release_short_lock
+ */
static inline int obd_reget_short_lock(struct obd_export *exp,
struct lov_stripe_md *lsm,
void **res, int rw,
@@ -1227,6 +1250,24 @@ static inline int obd_reget_short_lock(struct obd_export *exp,
start, end, cookie));
}
+
+/**
+ * Releases a reference to a lock taken in a "fast" way.
+ *
+ * Releases a read or write (specified by \a rw) lock
+ * referenced by \a cookie.
+ *
+ * \param exp obd export (lov or osc)
+ * \param lsm striping information for the file
+ * \param end end of the locked extent
+ * \param rw OBD_BRW_READ if requested for reading,
+ * OBD_BRW_WRITE if requested for writing
+ * \param cookie transparent parameter for passing locking context
+ *
+ * \post appropriate lock is dereferenced
+ *
+ * \see obd_reget_short_lock
+ */
static inline int obd_release_short_lock(struct obd_export *exp,
struct lov_stripe_md *lsm, obd_off end,
void *cookie, int rw)
diff --git a/lustre/ldlm/ldlm_lock.c b/lustre/ldlm/ldlm_lock.c
index dfe1a1761d..6aa3953a2b 100644
--- a/lustre/ldlm/ldlm_lock.c
+++ b/lustre/ldlm/ldlm_lock.c
@@ -919,6 +919,26 @@ void ldlm_lock_allow_match(struct ldlm_lock *lock)
unlock_res_and_lock(lock);
}
+/**
+ * Checks if requested extent lock is compatible with another owned lock.
+ *
+ * Checks if \a lock is compatible with a read or write lock
+ * (specified by \a rw) for an extent [\a start , \a end].
+ *
+ * \param lock the already owned lock
+ * \param rw OBD_BRW_READ if requested for reading,
+ * OBD_BRW_WRITE if requested for writing
+ * \param start start of the requested extent
+ * \param end end of the requested extent
+ * \param cookie transparent parameter for passing locking context
+ *
+ * \post result == 1, *cookie == context, appropriate lock is referenced
+ *
+ * \retval 1 owned lock is reused for the request
+ * \retval 0 no lock reused for the request
+ *
+ * \see ldlm_lock_fast_release
+ */
int ldlm_lock_fast_match(struct ldlm_lock *lock, int rw,
obd_off start, obd_off end,
void **cookie)
@@ -936,6 +956,20 @@ int ldlm_lock_fast_match(struct ldlm_lock *lock, int rw,
return 0;
}
+/**
+ * Releases a reference to a lock taken in a "fast" way.
+ *
+ * Releases a read or write (specified by \a rw) lock
+ * referenced by \a cookie.
+ *
+ * \param rw OBD_BRW_READ if requested for reading,
+ * OBD_BRW_WRITE if requested for writing
+ * \param cookie transparent parameter for passing locking context
+ *
+ * \post appropriate lock is dereferenced
+ *
+ * \see ldlm_lock_fast_lock
+ */
void ldlm_lock_fast_release(void *cookie, int rw)
{
struct ldlm_lock *lock = (struct ldlm_lock *)cookie;
diff --git a/lustre/llite/file.c b/lustre/llite/file.c
index 41f27238ae..9d90d513cc 100644
--- a/lustre/llite/file.c
+++ b/lustre/llite/file.c
@@ -1347,6 +1347,27 @@ out:
return rc;
}
+/**
+ * Checks if requested extent lock is compatible with a lock under a page.
+ *
+ * Checks if the lock under \a page is compatible with a read or write lock
+ * (specified by \a rw) for an extent [\a start , \a end].
+ *
+ * \param page the page under which lock is considered
+ * \param rw OBD_BRW_READ if requested for reading,
+ * OBD_BRW_WRITE if requested for writing
+ * \param start start of the requested extent
+ * \param end end of the requested extent
+ * \param cookie transparent parameter for passing locking context
+ *
+ * \post result == 1, *cookie == context, appropriate lock is referenced or
+ * \post result == 0
+ *
+ * \retval 1 owned lock is reused for the request
+ * \retval 0 no lock reused for the request
+ *
+ * \see ll_release_short_lock
+ */
static int ll_reget_short_lock(struct page *page, int rw,
obd_off start, obd_off end,
void **cookie)
@@ -1370,6 +1391,22 @@ static int ll_reget_short_lock(struct page *page, int rw,
cookie));
}
+/**
+ * Releases a reference to a lock taken in a "fast" way.
+ *
+ * Releases a read or a write (specified by \a rw) lock
+ * referenced by \a cookie.
+ *
+ * \param inode inode to which data belong
+ * \param end end of the locked extent
+ * \param rw OBD_BRW_READ if requested for reading,
+ * OBD_BRW_WRITE if requested for writing
+ * \param cookie transparent parameter for passing locking context
+ *
+ * \post appropriate lock is dereferenced
+ *
+ * \see ll_reget_short_lock
+ */
static void ll_release_short_lock(struct inode *inode, obd_off end,
void *cookie, int rw)
{
@@ -1386,6 +1423,29 @@ static void ll_release_short_lock(struct inode *inode, obd_off end,
CERROR("unlock failed (%d)\n", rc);
}
+/**
+ * Checks if requested extent lock is compatible
+ * with a lock under a page in page cache.
+ *
+ * Checks if a lock under some \a page is compatible with a read or write lock
+ * (specified by \a rw) for an extent [\a start , \a end].
+ *
+ * \param file the file under which lock is considered
+ * \param rw OBD_BRW_READ if requested for reading,
+ * OBD_BRW_WRITE if requested for writing
+ * \param ppos start of the requested extent
+ * \param end end of the requested extent
+ * \param cookie transparent parameter for passing locking context
+ * \param buf userspace buffer for the data
+ *
+ * \post result == 1, *cookie == context, appropriate lock is referenced
+ * \post retuls == 0
+ *
+ * \retval 1 owned lock is reused for the request
+ * \retval 0 no lock reused for the request
+ *
+ * \see ll_file_put_fast_lock
+ */
static inline int ll_file_get_fast_lock(struct file *file,
obd_off ppos, obd_off end,
char *buf, void **cookie, int rw)
@@ -1410,6 +1470,22 @@ static inline int ll_file_get_fast_lock(struct file *file,
RETURN(rc);
}
+/**
+ * Releases a reference to a lock taken in a "fast" way.
+ *
+ * Releases a read or a write (specified by \a rw) lock
+ * referenced by \a cookie.
+ *
+ * \param inode inode to which data belong
+ * \param end end of the locked extent
+ * \param rw OBD_BRW_READ if requested for reading,
+ * OBD_BRW_WRITE if requested for writing
+ * \param cookie transparent parameter for passing locking context
+ *
+ * \post appropriate lock is dereferenced
+ *
+ * \see ll_file_get_fast_lock
+ */
static inline void ll_file_put_fast_lock(struct inode *inode, obd_off end,
void *cookie, int rw)
{
@@ -1422,6 +1498,29 @@ enum ll_lock_style {
LL_LOCK_STYLE_TREELOCK = 2
};
+/**
+ * Checks if requested extent lock is compatible with a lock
+ * under a page cache page.
+ *
+ * Checks if the lock under \a page is compatible with a read or write lock
+ * (specified by \a rw) for an extent [\a start , \a end].
+ *
+ * \param file file under which I/O is processed
+ * \param rw OBD_BRW_READ if requested for reading,
+ * OBD_BRW_WRITE if requested for writing
+ * \param ppos start of the requested extent
+ * \param end end of the requested extent
+ * \param cookie transparent parameter for passing locking context
+ * (only used with LL_LOCK_STYLE_FASTLOCK)
+ * \param tree lock tree (only used with LL_LOCK_STYLE_TREELOCK)
+ * \param buf userspace buffer for the data
+ *
+ * \retval LL_LOCK_STYLE_FASTLOCK owned lock is reused through fast lock
+ * \retval LL_LOCK_STYLE_TREELOCK got a lock through tree lock
+ * \retval LL_LOCK_STYLE_NOLOCK got no lock
+ *
+ * \see ll_file_put_lock
+ */
static inline int ll_file_get_lock(struct file *file, obd_off ppos,
obd_off end, char *buf, void **cookie,
struct ll_lock_tree *tree, int rw)
@@ -1446,6 +1545,25 @@ static inline int ll_file_get_lock(struct file *file, obd_off ppos,
RETURN(rc);
}
+/**
+ * Drops the lock taken by ll_file_get_lock.
+ *
+ * Releases a read or a write (specified by \a rw) lock
+ * referenced by \a tree or \a cookie.
+ *
+ * \param inode inode to which data belong
+ * \param end end of the locked extent
+ * \param lockstyle facility through which the lock was taken
+ * \param rw OBD_BRW_READ if requested for reading,
+ * OBD_BRW_WRITE if requested for writing
+ * \param cookie transparent parameter for passing locking context
+ * (only used with LL_LOCK_STYLE_FASTLOCK)
+ * \param tree lock tree (only used with LL_LOCK_STYLE_TREELOCK)
+ *
+ * \post appropriate lock is dereferenced
+ *
+ * \see ll_file_get_lock
+ */
static inline void ll_file_put_lock(struct inode *inode, obd_off end,
enum ll_lock_style lock_style,
void *cookie, struct ll_lock_tree *tree,
diff --git a/lustre/lov/lov_obd.c b/lustre/lov/lov_obd.c
index b4b42639e6..3c8de91b8e 100644
--- a/lustre/lov/lov_obd.c
+++ b/lustre/lov/lov_obd.c
@@ -2832,6 +2832,29 @@ void lov_stripe_unlock(struct lov_stripe_md *md)
}
EXPORT_SYMBOL(lov_stripe_unlock);
+/**
+ * Checks if requested extent lock is compatible with a lock under the page.
+ *
+ * Checks if the lock under \a page is compatible with a read or write lock
+ * (specified by \a rw) for an extent [\a start , \a end].
+ *
+ * \param exp lov export
+ * \param lsm striping information for the file
+ * \param res lov_async_page placeholder
+ * \param rw OBD_BRW_READ if requested for reading,
+ * OBD_BRW_WRITE if requested for writing
+ * \param start start of the requested extent
+ * \param end end of the requested extent
+ * \param cookie transparent parameter for passing locking context
+ *
+ * \post result == 1, *cookie == context, appropriate lock is referenced or
+ * \post result == 0
+ *
+ * \retval 1 owned lock is reused for the request
+ * \retval 0 no lock reused for the request
+ *
+ * \see lov_release_short_lock
+ */
static int lov_reget_short_lock(struct obd_export *exp,
struct lov_stripe_md *lsm,
void **res, int rw,
@@ -2858,6 +2881,23 @@ static int lov_reget_short_lock(struct obd_export *exp,
rw, stripe_start, stripe_end, cookie));
}
+/**
+ * Releases a reference to a lock taken in a "fast" way.
+ *
+ * Releases a read or a write (specified by \a rw) lock
+ * referenced by \a cookie.
+ *
+ * \param exp lov export
+ * \param lsm striping information for the file
+ * \param end end of the locked extent
+ * \param rw OBD_BRW_READ if requested for reading,
+ * OBD_BRW_WRITE if requested for writing
+ * \param cookie transparent parameter for passing locking context
+ *
+ * \post appropriate lock is dereferenced
+ *
+ * \see lov_reget_short_lock
+ */
static int lov_release_short_lock(struct obd_export *exp,
struct lov_stripe_md *lsm, obd_off end,
void *cookie, int rw)
diff --git a/lustre/osc/osc_request.c b/lustre/osc/osc_request.c
index 24f7530403..ec59eb95ac 100644
--- a/lustre/osc/osc_request.c
+++ b/lustre/osc/osc_request.c
@@ -2554,6 +2554,29 @@ static int osc_enter_cache(struct client_obd *cli, struct lov_oinfo *loi,
RETURN(-EDQUOT);
}
+/**
+ * Checks if requested extent lock is compatible with a lock under the page.
+ *
+ * Checks if the lock under \a page is compatible with a read or write lock
+ * (specified by \a rw) for an extent [\a start , \a end].
+ *
+ * \param exp osc export
+ * \param lsm striping information for the file
+ * \param res osc_async_page placeholder
+ * \param rw OBD_BRW_READ if requested for reading,
+ * OBD_BRW_WRITE if requested for writing
+ * \param start start of the requested extent
+ * \param end end of the requested extent
+ * \param cookie transparent parameter for passing locking context
+ *
+ * \post result == 1, *cookie == context, appropriate lock is referenced or
+ * \post result == 0
+ *
+ * \retval 1 owned lock is reused for the request
+ * \retval 0 no lock reused for the request
+ *
+ * \see osc_release_short_lock
+ */
static int osc_reget_short_lock(struct obd_export *exp,
struct lov_stripe_md *lsm,
void **res, int rw,
@@ -2573,6 +2596,23 @@ static int osc_reget_short_lock(struct obd_export *exp,
RETURN(rc);
}
+/**
+ * Releases a reference to a lock taken in a "fast" way.
+ *
+ * Releases a read or a write (specified by \a rw) lock
+ * referenced by \a cookie.
+ *
+ * \param exp osc export
+ * \param lsm striping information for the file
+ * \param end end of the locked extent
+ * \param rw OBD_BRW_READ if requested for reading,
+ * OBD_BRW_WRITE if requested for writing
+ * \param cookie transparent parameter for passing locking context
+ *
+ * \post appropriate lock is dereferenced
+ *
+ * \see osc_reget_short_lock
+ */
static int osc_release_short_lock(struct obd_export *exp,
struct lov_stripe_md *lsm, obd_off end,
void *cookie, int rw)
--
GitLab