Documentation/filesystems/gfs2/glocks.rst

Source file repositories/reference/linux-study-clean/Documentation/filesystems/gfs2/glocks.rst

File Facts

System
Linux kernel
Corpus path
Documentation/filesystems/gfs2/glocks.rst
Extension
.rst
Size
11325 bytes
Lines
250
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

.. SPDX-License-Identifier: GPL-2.0

============================
Glock internal locking rules
============================

This documents the basic principles of the glock state machine
internals. Each glock (struct gfs2_glock in fs/gfs2/incore.h)
has two main (internal) locks:

 1. A spinlock (gl_lockref.lock) which protects the internal state such
    as gl_state, gl_target and the list of holders (gl_holders)
 2. A non-blocking bit lock, GLF_LOCK, which is used to prevent other
    threads from making calls to the DLM, etc. at the same time. If a
    thread takes this lock, it must then call run_queue (usually via the
    workqueue) when it releases it in order to ensure any pending tasks
    are completed.

The gl_holders list contains all the queued lock requests (not
just the holders) associated with the glock. If there are any
held locks, then they will be contiguous entries at the head
of the list. Locks are granted in strictly the order that they
are queued.

There are three lock states that users of the glock layer can request,
namely shared (SH), deferred (DF) and exclusive (EX). Those translate
to the following DLM lock modes:

==========	====== =====================================================
Glock mode      DLM    lock mode
==========	====== =====================================================
    UN          IV/NL  Unlocked (no DLM lock associated with glock) or NL
    SH          PR     (Protected read)
    DF          CW     (Concurrent write)
    EX          EX     (Exclusive)
==========	====== =====================================================

Thus DF is basically a shared mode which is incompatible with the "normal"
shared lock mode, SH. In GFS2 the DF mode is used exclusively for direct I/O
operations. The glocks are basically a lock plus some routines which deal
with cache management. The following rules apply for the cache:

==========      ==============   ==========   ==========   ==============
Glock mode      Cache Metadata   Cache data   Dirty Data   Dirty Metadata
==========      ==============   ==========   ==========   ==============
    UN                No            No            No            No
    DF                Yes           No            No            No
    SH                Yes           Yes           No            No
    EX                Yes           Yes           Yes           Yes
==========      ==============   ==========   ==========   ==============

These rules are implemented using the various glock operations which
are defined for each type of glock. Not all types of glocks use
all the modes. Only inode glocks use the DF mode for example.

Table of glock operations and per type constants:

==============     =============================================================
Field              Purpose
==============     =============================================================
go_sync            Called before remote state change (e.g. to sync dirty data)
go_xmote_bh        Called after remote state change (e.g. to refill cache)
go_inval           Called if remote state change requires invalidating the cache
go_instantiate     Called when a glock has been acquired
go_held            Called every time a glock holder is acquired
go_dump            Called to print content of object for debugfs file, or on
                   error to dump glock to the log.
go_callback	   Called if the DLM sends a callback to drop this lock
go_unlocked        Called when a glock is unlocked (dlm_unlock())
go_type            The type of the glock, ``LM_TYPE_*``

Annotation

Implementation Notes