9P-FID(3)

💅 9P-FID(3) — Library Functions Manual, bestie ✨

okay so this is the 9P-FID(3) page from the Library Functions Manual, and we are about to make fid/request tracking make sense, fr fr. 🎀

🎀 NAME 🎀

Fid, Fidpool, allocfidpool, freefidpool, allocfid, closefid, lookupfid, removefid, Req, Reqpool, allocreqpool, freereqpool, allocreq, closereq, lookupreq, removereq — 9P fid, request tracking 💖

✨ SYNOPSIS ✨

the literal spellbook, copy-paste exact bestie:

#include <u.h>
#include <libc.h>
#include <fcall.h>
#include <thread.h>
#include <9p.h>

typedef struct Fid
{
    ulong fid;
    char  omode;  /* -1 if not open */
    char  *uid;
    Qid   qid;
    File  *file;
    void  *aux;
    ...
} Fid;

typedef struct Req
{
    ulong tag;
    Fcall ifcall;
    Fcall ofcall;
    Req   *oldreq;
    void  *aux;
    ...
} Req;

Fidpool* allocfidpool(void (*destroy)(Fid*))
void     freefidpool(Fidpool *p)
Fid*     allocfid(Fidpool *p, ulong fid)
Fid*     lookupfid(Fidpool *p, ulong fid)
void     closefid(Fid *f)
void     removefid(Fid *f)

Reqpool* allocreqpool(void (*destroy)(Req*))
void     freereqpool(Reqpool *p)
Req*     allocreq(Reqpool *p, ulong tag)
Req*     lookupreq(Reqpool *p, ulong tag)
void     closereq(Req *f)
void     removereq(Req *r)

🦋 DESCRIPTION 🦋

These routines are the whole management situation for Fid and Req structures from Fidpools and Reqpools. They're primarily used by the 9P server loop described in 9p(3), iykyk.

Fid structures are intended to represent active fids in a 9P connection, exactly like Chan structures do in the Plan 9 kernel. The fid element is the integer fid used in the 9P connection. Omode is the mode under which the fid was opened, or -1 if this fid has not been opened yet. Note that in addition to the values OREAD, OWRITE, and ORDWR, omode can contain the various flags permissible in an open call. To ignore the flags, use omode&OMASK.

⚠️ Omode should not be changed by the client, bestie. That is not the vibe. 🙈

The fid derives from a successful authentication by uid. Qid contains the qid returned in the last successful walk or create transaction involving the fid. In a file tree-based server, the Fid's file element points at a File structure (see 9p-file(3)) corresponding to the fid. The aux member is intended for use by the client to hold information specific to a particular Fid. With the exception of aux, these elements should be treated as read-only by the client. 💅

Allocfidpool creates a new Fidpool. Freefidpool destroys such a pool. Allocfid returns a new Fid whose fid number is fid. There must not already be an extant Fid with that number in the pool. Once a Fid has been allocated, it can be looked up by fid number using lookupfid. Fids are reference counted: both allocfid and lookupfid increment the reference count on the Fid structure before returning. When a reference to a Fid is no longer needed, closefid should be called to note the destruction of the reference. When the last reference to a Fid is removed, if destroy (supplied when creating the fid pool) is not zero, it is called with the Fid as a parameter. It should perform whatever cleanup is necessary regarding the aux element. Removefid is equivalent to closefid but also removes the Fid from the pool.

👀 Note that due to lingering references, the return of removefid may not mean that destroy has been called. So don't assume, bestie. 😭

Allocreqpool, freereqpool, allocreq, lookupreq, closereq, and removereq are analogous but operate on Reqpools and Req structures. Same energy, different struct. 🦋

🌈 SOURCE 🌈

/src/lib9p — that's the spot. 🫶

👑 SEE ALSO 👑

9p(3), 9p-file(3) — go read those too, they're iconic. ✨

💖 okay that's the whole page, bestie! 9P-FID(3) — Library Functions Manual, source /src/lib9p — and the footer doesn't give us a date, so no cap, just vibes. 🎀