Documentation/core-api/watch_queue.rst

Source file repositories/reference/linux-study-clean/Documentation/core-api/watch_queue.rst

File Facts

System
Linux kernel
Corpus path
Documentation/core-api/watch_queue.rst
Extension
.rst
Size
11679 bytes
Lines
344
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

struct watch_notification {
		__u32	type:24;
		__u32	subtype:8;
		__u32	info;
	};

"type" indicates the source of the notification record and "subtype" indicates
the type of record from that source (see the Watch Sources section below).  The
type may also be "WATCH_TYPE_META".  This is a special record type generated
internally by the watch queue itself.  There are two subtypes:

  * WATCH_META_REMOVAL_NOTIFICATION
  * WATCH_META_LOSS_NOTIFICATION

The first indicates that an object on which a watch was installed was removed
or destroyed and the second indicates that some messages have been lost.

"info" indicates a bunch of things, including:

  * The length of the message in bytes, including the header (mask with
    WATCH_INFO_LENGTH and shift by WATCH_INFO_LENGTH__SHIFT).  This indicates
    the size of the record, which may be between 8 and 127 bytes.

  * The watch ID (mask with WATCH_INFO_ID and shift by WATCH_INFO_ID__SHIFT).
    This indicates that caller's ID of the watch, which may be between 0
    and 255.  Multiple watches may share a queue, and this provides a means to
    distinguish them.

  * A type-specific field (WATCH_INFO_TYPE_INFO).  This is set by the
    notification producer to indicate some meaning specific to the type and
    subtype.

Everything in info apart from the length can be used for filtering.

The header can be followed by supplementary information.  The format of this is
at the discretion is defined by the type and subtype.


Watch List (Notification Source) API
====================================

A "watch list" is a list of watchers that are subscribed to a source of
notifications.  A list may be attached to an object (say a key or a superblock)
or may be global (say for device events).  From a userspace perspective, a
non-global watch list is typically referred to by reference to the object it
belongs to (such as using KEYCTL_NOTIFY and giving it a key serial number to
watch that specific key).

To manage a watch list, the following functions are provided:

  * ::

	void init_watch_list(struct watch_list *wlist,
			     void (*release_watch)(struct watch *wlist));

    Initialise a watch list.  If ``release_watch`` is not NULL, then this
    indicates a function that should be called when the watch_list object is
    destroyed to discard any references the watch list holds on the watched
    object.

  * ``void remove_watch_list(struct watch_list *wlist);``

    This removes all of the watches subscribed to a watch_list and frees them
    and then destroys the watch_list object itself.


Watch Queue (Notification Output) API
=====================================

A "watch queue" is the buffer allocated by an application that notification

Annotation

Implementation Notes