LLAPI_HSM_ACTION_BEGIN(3)

📦 version 2.17.58, in ubuntu stonking

💖 LLAPI_HSM_ACTION_BEGIN 💖 — the Lustre library functions girlies know

okay bestie, so this is a page from the Lustre Library Functions manual (section 3, iykyk) and it's about the whole copytool management saga. Five functions, one friend group. let's get into it 🫶

✨ NAME ✨

llapi_hsm_action_begin, llapi_hsm_action_end, llapi_hsm_action_progress, llapi_hsm_action_get_dfid, llapi_hsm_action_get_fd — the Lustre API copytool management crew 👑

🌸 SYNOPSIS 🌸

#include <lustre/lustreapi.h>

int llapi_hsm_action_begin(struct hsm_copyaction_private **phcp,
                           const struct hsm_copytool_private *ct,
                           const struct hsm_action_item *hai,
                           int restore_mdt_index,
                           int restore_open_flags, bool is_error);

int llapi_hsm_action_end(struct hsm_copyaction_private **phcp,
                         const struct hsm_extent *he, int hp_flags,
                         int errval);

int llapi_hsm_action_progress(struct hsm_copyaction_private *hcp,
                              const struct hsm_extent *he,
                              __u64 total, int hp_flags);

int llapi_hsm_action_get_dfid(const struct hsm_copyaction_private *hcp,
                              lustre_fid  *fid);

int llapi_hsm_action_get_fd(const struct hsm_copyaction_private *hcp);

just copy it verbatim, don't get cute with it, copy-paste is the move 💅

🦋 DESCRIPTION 🦋

So your copytool just got an HSM action through llapi_hsm_copytool_recv() and it's ready to cook. Before it does literally anything else, it must call llapi_hsm_action_begin() first — that's the vibe check that sets up the internal action state, and that state lives in phcp. 🎀

a lil breakdown of the args:

  • ct — the opaque copytool handle, aka the thing llapi_hsm_copytool_register() handed you earlier
  • hai — the request itself
  • restore_mdt_index and restore_open_flags — these two are only used when the request is type HSMA_RESTORE. restore_mdt_index is the MDT index where the restored file gets created, or -1 for the default. no notes.
  • is_error — if your copytool is not planning to process this request at all, set is_error to true, and then go ahead and call llapi_hsm_action_end(). that's the graceful exit bestie.

While the copy is actually happening (i.e. the HSM request is either HSMA_ARCHIVE or HSMA_RESTORE), your copytool can keep Lustre posted on how it's going with llapi_hsm_action_progress(). 🌈

  • he is the interval — (offset, length) — of the data that got copied.
  • Every single interval must be unique. no overlapping, periodt. seriously, don't.
  • length is the total length that's expected to be transferred.
  • hp_flags should be 0. just zero. that's it.

and the fun part: you can peek at the progress from any Lustre client, either by calling llapi_hsm_current_action(), or by using lfshsm_action. obsessed with the cross-node visibility tbh ✨

Once the HSM request is done, the destination file must be closed, and then llapi_hsm_action_end() must be called — that's what frees up the allocated resources and signals to Lustre that the file is now available to consumers. freeing your friends (and resources) is the whole energy 🫶

  • errval is set to 0 on success.
  • On error, it has to be an errno.
  • hp_flags can be set to HP_FLAG_RETRY if the request is retryable, otherwise 0.
  • he is the interval (offset, length) of the data copied — it can be the hai_extent of the HSM request. convenient, honestly.

For a restore operation, a volatile file gets created — and it's invisible to ls. spooky but make it fashion 👻

  • llapi_hsm_action_get_fd() returns a file descriptor to it. it is your responsibility as the copytool to close that returned file descriptor once the data transfer is done. don't leave it hanging, that's rude.
  • llapi_hsm_action_get_dfid() returns the FID of the volatile file. you can then pass that to llapi_open_by_fid() to open the file in a different process, or even on a different node. main character multiverse energy 🔥

plot twist: llapi_hsm_action_get_fd() and llapi_hsm_action_get_dfid() can be called for an archive operation too! in that case, the file descriptor and the FID you get back are from the file to be archived. same functions, different context, we love a flexible queen 💜

💀 RETURN VALUE 💀

  • llapi_hsm_action_get_fd() returns a file descriptor on success.
  • The other functions return 0 on success.
  • All of them return a negative errno on failure. that's the "it's not giving" signal, ngl.

🙈 ERRORS 🙈

The negative errno can be, but is not limited to:

  • -EINVAL — An invalid value was passed, the copytool is not registered, ...
  • -ENOMEM — Not enough memory to allocate a resource.
"but is not limited to" means there could be more, bestie — don't come for me if you hit something else 😭

👑 AUTHORS 👑

Frank Zago

⭐ AVAILABILITY ⭐

llapi_hsm_action_begin(), llapi_hsm_action_end(), llapi_hsm_action_progress(), llapi_hsm_action_get_dfid() and llapi_hsm_action_get_fd() are all part of the lustre(7) user application interface library since release 2.4.0. yes, they've been iconic for a while 🌸

🧚 SEE ALSO 🧚

and if you want a real-life use case of this API, go look at lhsmtool_posix.c in the Lustre sources. it's giving reference implementation ✨

aaaand that's the page, bestie 💖 this was Lustre User API, dated 2024-08-27, and it lives under LLAPI_HSM_ACTION_BEGIN(3) — go forth and manage your copytools, you've absolutely got this. slay, no cap 🎀🦋💅

📦 where this page comes from