rtapi_clock_set_period(3rtapi)

✨ rtapi_clock_set_period ✨

okay bestie, so this is a page from the RTAPI manual — that's the realtime API layer, and this little function right here is the one that sets the vibe (the clock period, technically, but vibe works too 💅). It's rtapi_clock_set_period, and it's literally the thing that decides how often your realtime tasks get to show up.

---

🎀 NAME 🎀

rtapi_clock_set_period — set the basic time interval for realtime tasks

like, the fundamental tick. the heartbeat. the metronome of your whole realtime world 🫶

---

🌸 SYNTAX 🌸

rtapi_clock_set_period(long int nsec)

that's it. one argument. she's simple, she's iconic, she's not doing too much 👑

---

🦋 ARGUMENTS 🦋

• nsec — the desired basic time interval for realtime tasks. your dream period, in nanoseconds, bestie ✨

---

💖 DESCRIPTION 💖

so here's the tea: rtapi_clock_set_period sets the basic time interval for realtime tasks. all periodic tasks will run at an integer multiple of this period — so whatever you set here is basically the base unit that everything else is measured in. main character energy for real 🎀

the first call to rtapi_clock_set_period with nsec greater than zero will start the clock, using nsec as the clock period in nano-seconds. and like... no pressure, but that's the one that counts. the first one. the debut. 🦋

⚠️ due to hardware and RTOS limitations, the actual period may not be exactly what was requested. not me asking for a perfect number and getting... whatever the hardware felt like 😭

on success, the function will return the actual clock period if it is available, otherwise it returns the requested period. so sometimes you get the real answer, sometimes you get the polite answer. either way, slay.

if the requested period is outside the limits imposed by the hardware or RTOS, it returns -EINVAL and does not start the clock. that's a hard no from the system. respect the limits, bestie 💀

once the clock is started, subsequent calls with non-zero nsec return -EINVAL and have no effect. the clock has already made its decision. she's not taking notes. periodt. 💅

calling rtapi_clock_set_period with nsec set to zero queries the clock, returning the current clock period, or zero if the clock has not yet been started. that's your little status check, like sliding into your own DMs to see if anything's happening yet 👀

---

🌈 REALTIME CONSIDERATIONS 🌈

• call only from within init/cleanup code, not from realtime tasks 🚫
• this function is not available from non-realtime code 🚫

so like, know your lane. init/cleanup only. don't be calling this from a realtime task, that's not the move, ngl 🙈

---

⭐ RETURN VALUE ⭐

the actual period provided by the RTOS — which may be different than the requested period — or a RTAPI status code.

yeah. she might lowkey do her own thing. that's just how it is 🤷♀️

---

and that's the whole page, bestie, no notes 💖 that was rtapi_clock_set_period(3rtapi) from the LinuxCNC Documentation, dated 2006-10-12 — yes, she's been serving since 2006 and she still ate. iykyk 🎀✨🌸