lib.interlink: integrate with shm.open_frame for snabb top

This adds auxiliary code to help tools like `snabb top -l' print meaningful
descriptions of shared memory interlink objects. I.e., in order to get some
useful debugging information about inter-process links used by a Snabb process
one could do

  $ snabb top -l group/interlink
  some_interlink                0/1024 (waiting for transmitter)
  …

which shows the occupancy (<fill>/<capacity>) and status of the queue.

src/apps/interlink/receiver.lua

@@ -9,8 +9,8 @@ local Receiver = {name="apps.interlink.Receiver"}
 
 function Receiver:new (_, name)
    local self = {}
-   self.shm_name = "group/interlink/"..name
-   self.backlink = "interlink/receiver/"..name
+   self.shm_name = "group/interlink/"..name..".interlink"
+   self.backlink = "interlink/receiver/"..name..".interlink"
    self.interlink = interlink.attach_receiver(self.shm_name)
    shm.alias(self.backlink, self.shm_name)
    return setmetatable(self, {__index=Receiver})
@@ -37,8 +37,8 @@ end
 -- process termination.
 function Receiver.shutdown (pid)
    for _, name in ipairs(shm.children("/"..pid.."/interlink/receiver")) do
-      local backlink = "/"..pid.."/interlink/receiver/"..name
-      local shm_name = "/"..pid.."/group/interlink/"..name
+      local backlink = "/"..pid.."/interlink/receiver/"..name..".interlink"
+      local shm_name = "/"..pid.."/group/interlink/"..name..".interlink"
       -- Call protected in case /<pid>/group is already unlinked.
       local ok, r = pcall(interlink.open, shm_name)
       if ok then interlink.detach_receiver(r, shm_name) end

src/apps/interlink/transmitter.lua

@@ -9,8 +9,8 @@ local Transmitter = {name="apps.interlink.Transmitter"}
 
 function Transmitter:new (_, name)
    local self = {}
-   self.shm_name = "group/interlink/"..name
-   self.backlink = "interlink/transmitter/"..name
+   self.shm_name = "group/interlink/"..name..".interlink"
+   self.backlink = "interlink/transmitter/"..name..".interlink"
    self.interlink = interlink.attach_transmitter(self.shm_name)
    shm.alias(self.backlink, self.shm_name)
    return setmetatable(self, {__index=Transmitter})
@@ -37,8 +37,8 @@ end
 -- process termination.
 function Transmitter.shutdown (pid)
    for _, name in ipairs(shm.children("/"..pid.."/interlink/transmitter")) do
-      local backlink = "/"..pid.."/interlink/transmitter/"..name
-      local shm_name = "/"..pid.."/group/interlink/"..name
+      local backlink = "/"..pid.."/interlink/transmitter/"..name..".interlink"
+      local shm_name = "/"..pid.."/group/interlink/"..name..".interlink"
       -- Call protected in case /<pid>/group is already unlinked.
       local ok, r = pcall(interlink.open, shm_name)
       if ok then interlink.detach_transmitter(r, shm_name) end

src/lib/interlink.lua

@@ -244,6 +244,32 @@ function pull (r)
    r.read = r.nread
 end
 
+-- The code below registers an abstract SHM object type with core.shm, and
+-- implements the minimum API necessary for programs like snabb top to inspect
+-- interlink queues (including a tostring meta-method to describe queue
+-- objects.)
+
+shm.register('interlink', getfenv())
+
 function open (name, readonly)
    return shm.open(name, "struct interlink", readonly)
 end
+
+local function describe (r)
+   local function queue_fill (r)
+      local read, write = r.read, r.write
+      return read > write and write + SIZE - read or write - read
+   end
+   local function status (r)
+      return ({
+         [FREE] = "initializing",
+         [RXUP] = "waiting for transmitter",
+         [TXUP] = "waiting for receiver",
+         [DXUP] = "in active use",
+         [DOWN] = "deallocating"
+      })[r.state[0]]
+   end
+   return ("%d/%d (%s)"):format(queue_fill(r), SIZE, status(r))
+end
+
+ffi.metatype(ffi.typeof("struct interlink"), {__tostring=describe})

src/program/top/top.lua

@@ -11,6 +11,10 @@ local S = require("syscall")
 local histogram = require("core.histogram")
 local usage = require("program.top.README_inc")
 
+-- We must load any modules that register abstract shm types that we may
+-- wish to inspect.
+require("lib.interlink")
+
 local long_opts = {
    help = "h", list = "l"
 }