Documentation/core-api/errseq.rst

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

File Facts

System
Linux kernel
Corpus path
Documentation/core-api/errseq.rst
Extension
.rst
Size
6585 bytes
Lines
160
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 worker_drone {
                errseq_t        wd_err; /* for recording errors */
        };

Every day, the worker_drone starts out with a blank slate::

        struct worker_drone wd;

        wd.wd_err = (errseq_t)0;

The supervisors come in and get an initial read for the day.  They
don't care about anything that happened before their watch begins::

        struct supervisor {
                errseq_t        s_wd_err; /* private "cursor" for wd_err */
                spinlock_t      s_wd_err_lock; /* protects s_wd_err */
        }

        struct supervisor       su;

        su.s_wd_err = errseq_sample(&wd.wd_err);
        spin_lock_init(&su.s_wd_err_lock);

Now they start handing him tasks to do.  Every few minutes they ask him to
finish up all of the work they've handed him so far.  Then they ask him
whether he made any mistakes on any of it::

        spin_lock(&su.su_wd_err_lock);
        err = errseq_check_and_advance(&wd.wd_err, &su.s_wd_err);
        spin_unlock(&su.su_wd_err_lock);

Up to this point, that just keeps returning 0.

Now, the owners of this company are quite miserly and have given him
substandard equipment with which to do his job. Occasionally it
glitches and he makes a mistake.  He sighs a heavy sigh, and marks it
down::

        errseq_set(&wd.wd_err, -EIO);

...and then gets back to work.  The supervisors eventually poll again
and they each get the error when they next check.  Subsequent calls will
return 0, until another error is recorded, at which point it's reported
to each of them once.

Note that the supervisors can't tell how many mistakes he made, only
whether one was made since they last checked, and the latest value
recorded.

Occasionally the big boss comes in for a spot check and asks the worker
to do a one-off job for him. He's not really watching the worker
full-time like the supervisors, but he does need to know whether a
mistake occurred while his job was processing.

He can just sample the current errseq_t in the worker, and then use that
to tell whether an error has occurred later::

        errseq_t since = errseq_sample(&wd.wd_err);
        /* submit some work and wait for it to complete */
        err = errseq_check(&wd.wd_err, since);

Since he's just going to discard "since" after that point, he doesn't
need to advance it here. He also doesn't need any locking since it's
not usable by anyone else.

Serializing errseq_t cursor updates
===================================

Note that the errseq_t API does not protect the errseq_t cursor during a
check_and_advance_operation. Only the canonical error code is handled

Annotation

Implementation Notes