Skip to content

Add lunatik objects to README - #340

Closed
sneaky-potato wants to merge 1 commit into
luainkernel:masterfrom
sneaky-potato:lunatik-objects-docs
Closed

sneaky-potato wants to merge 1 commit into
luainkernel:masterfrom
sneaky-potato:lunatik-objects-docs

Conversation

@sneaky-potato

Copy link
Copy Markdown
Member

Fixes #183

Signed-off-by: Ashwani Kumar Kamal <ashwanikamal.im421@gmail.com>
Comment thread README.md

The lifetime of an object is not tied solely to Lua garbage collection. An object remains alive as long as at least one reference exists.

Some objects expose an explicit *stop* or *close* operation, which releases internal resources (such as Lua states or kernel hooks) before the object itself is freed.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"Lua states" seems misleading here.. see https://www.lua.org/manual/5.4/manual.html#lua_State

Comment thread README.md

Lua garbage collection may release Lua references to an object, but this does not necessarily destroy the underlying kernel object. Garbage collection typically results in a reference counter decrement.

Kernel-held references keep the object alive even after all Lua references are gone. For deterministic cleanup, objects should be explicitly stopped or unloaded when appropriate.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

can you give an example?

Comment thread README.md
Lunatik exposes kernel facilities to Lua through *objects*. A Lunatik object is a Lua userdata that represents a kernel-resident resource and is shared between Lua and C code.

Internally, each Lunatik object combines:
- a Lua userdata

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

per runtime, right? each object might correspond to many userdata.

@lneto

lneto commented Jan 17, 2026

Copy link
Copy Markdown
Contributor

@sneaky-potato are you still working on this?

@sneaky-potato

sneaky-potato commented Jan 17, 2026 •

Copy link
Copy Markdown
Member Author

Hi @lneto , yes. I’ve been a bit caught up with other work lately, but I haven’t dropped it and will resume once things free up. Thanks for checking! I will mark the PR as draft for now.

@sneaky-potato
sneaky-potato marked this pull request as draft January 17, 2026 19:22
@lneto

lneto commented Jan 17, 2026

Copy link
Copy Markdown
Contributor

Hi @lneto , yes. I’ve been a bit caught up with other work lately, but I haven’t dropped it and will resume once things free up. Thanks for checking! I will mark the PR as draft for now.

No worries, I'm just planning the next release.. thanks!

@lneto

lneto commented Sep 15, 2026

Copy link
Copy Markdown
Contributor

Agent comment (Claude Code), posted from @lneto's account.

doc/capi.md now owns this ground more precisely than a README section could: it documents the object model, the class flags and the lifetime of a Lunatik object for the reader writing a binding, and the README's module table points at the bindings themselves. The three review comments on this pull request were never addressed, and one of its claims, that an object is a userdata, is not how the model works: the userdata is the handle a Lua state holds, and the object outlives it through its kref. Closing in favour of doc/capi.md; a README change that points readers there would be welcome as its own pull request.

@lneto lneto closed this Sep 15, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

add documentation for Lunatik objects

2 participants