drmaa2_list(3)

💖 drmaa2_list(3) 💖

okay bestie, so this is a page from the Library Functions Manual — it's all about drmaa2_list, the DRMAA2 list routines. lists!! the backbone of everything!! let's get into it 🦋

---

✨ NAME ✨

DRMAA2 list routines — the lil collection-type besties that hold your strings, jobs, queue info, machine info, slot info and reservations 💅

---

✨ SYNOPSIS ✨

#include "drmaa.h"
struct drmaa2_list_s;        /*forward*/
typedef struct drmaa2_list_s *drmaa2_list;
typedef struct drmaa2_list_s *drmaa2_string_list;
typedef struct drmaa2_list_s *drmaa2_j_list;
typedef struct drmaa2_list_s *drmaa2_queueinfo_list;
typedef struct drmaa2_list_s *drmaa2_machineinfo_list;
typedef struct drmaa2_list_s *drmaa2_slotinfo_list;
typedef struct drmaa2_list_s *drmaa2_r_list;

typedef enum drmaa2_listtype {
  DRMAA2_STRINGLIST,
  DRMAA2_JOBLIST,
  DRMAA2_QUEUEINFOLIST,
  DRMAA2_MACHINEINFOLIST,
  DRMAA2_SLOTINFOLIST,
  DRMAA2_RESERVATIONLIST
} drmaa2_listtype;

typedef void (*drmaa2_list_entryfree)(void **value);
drmaa2_list drmaa2_list_create (const drmaa2_listtype t, const drmaa2_list_entryfree callback);
void drmaa2_list_free(drmaa2_list *l);
const void *drmaa2_list_get(const drmaa2_list l, long pos);
drmaa2_error drmaa2_list_add(drmaa2_list l, const void *value);
drmaa2_error drmaa2_list_del(drmaa2_list l, long pos);
long drmaa2_list_size(const drmaa2_list l);

like. look at all those typedefs. it's giving typed list buffet 🌈 and yes, DRMAA2_STRINGLIST, DRMAA2_JOBLIST, DRMAA2_QUEUEINFOLIST, DRMAA2_MACHINEINFOLIST, DRMAA2_SLOTINFOLIST and DRMAA2_RESERVATIONLIST are the whole drmaa2_listtype enum, no skips, no crumbs 💖

---

✨ DESCRIPTION ✨

okay so here's the tea on every single one of these functions, no gatekeeping 🫶

🌸 drmaa2_list_create()

creates a brand new list instance for the type of items you specified. it hands you back a pointer to the list — or NULL if something went wrong 😭

the optional callback parameter lets your application hand over a callback pointer to a collection element cleanup function. and listen — DRMAA2_UNSET_CALLBACK may be supplied instead of a valid callback pointer. so you're not forced to bring a callback to the function, it's chill like that ✨

🌸 drmaa2_list_free()

frees the list and the contained members. periodt.

if a callback function was provided on list creation, it SHALL be called once per list item. once per item!! so if your callback is messy, that's a you problem bestie 💀

🌸 drmaa2_list_get()

gets the list element at the indicated position. the element index starts at zero (zero-indexed, as the universe intended 👑). if the index is invalid, the function returns NULL. that's it, that's the whole vibe.

🌸 drmaa2_list_add()

adds a new item at the end of the list and returns a success indication. and here's the important part, no cap: the list MUST contain only the provided pointer, not a deep copy of the provided data structure. just the pointer. the address. the location. nothing deeper 🫡

🌸 drmaa2_list_del()

removes the list element at the indicated position and returns a success indication. if a callback function was provided on list creation, it SHALL be called before this function returns. before!! the callback gets its moment first 💅

🌸 drmaa2_list_size()

returns the number of elements in the list. if the list is empty, then the function returns 0, which SHALL NOT be treated as an error case. zero is not an error!! zero is just a small slay!! don't come for empty lists 😤

---

✨ SEE ALSO ✨

• drmaa2(3)
• drmaa2_dict(3)

---

and that's the whole page bestie, you ate it, you understood it, iconic behavior 💜

✧･ﾟ: * this came from the Library Functions Manual, dated 2012-12-01 * :･ﾟ✧