oak-team/oak-editor
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

refactor(node): switch oaknode to refcounted value handles, migrate consumers

Browse Source 
- all 15 OakNode* handle types become neutral by-value structs
  {ctx, addref, release, abi_version}; shared box in
  src/node/c_api/nodehandle.h with owns flag (borrowed accessors
  return non-owning boxes; graph insertion flips owns off)
- oaktimeline/oaktask/oakrender call sites and their own public
  headers migrated to value handles; identity comparisons in
  timeline/task now compare native pointers
- regressions green: oaknode 96, oaktimeline 117, oaktask 106,
  oakrender 44, oakcommon 193, oakcodec 18, oakaudio 36
This commit is contained in:
Mike-Solar
2026-08-07 17:20:42 +08:00
parent 295ea1bfe5
commit 67176281d9
87 changed files with 4499 additions and 3431 deletions
Download Patch File Download Diff File Expand all files Collapse all files
include/node/project.h
+68 -44
View File
@@ -21,6 +21,8 @@
#ifndef OAK_EDITOR_NODE_PROJECT_H
#define OAK_EDITOR_NODE_PROJECT_H
#include <stdint.h>
#include "node/error.h"
#ifdef __cplusplus
@@ -33,9 +35,9 @@ extern "C" {
*
* An OakNodeProject owns its whole node graph: nodes added with
* oaknode_project_add_node() (directly, or indirectly through the folder and
* footage families) are deleted by oaknode_project_free(). Handles to nodes,
* folders and footage obtained from a project are borrowed views and must not
* be freed.
* footage families) are deleted when the project's last reference is
* released. Handles to nodes, folders and footage obtained from a project
* are borrowed views: releasing them only releases the handle itself.
*
* Conventions (shared by all oaknode C API families):
* - Return codes: 0 (OAKNODE_OK) on success, a negative OAKNODE_E_* code on
@@ -44,27 +46,37 @@ extern "C" {
* query the required size; the return value is the required buffer size in
* bytes INCLUDING the terminating NUL. The output is NUL-terminated
* whenever buf_size > 0.
* - NULL handles yield OAKNODE_E_INVALID (or a no-op for free()).
* - Empty handles (ctx == NULL) yield OAKNODE_E_INVALID (or a no-op for
* free()).
* - Disk save/load of project files is NOT part of this layer; it belongs to
* oakstorage (milestone M10).
*/
/**
* @brief Opaque project handle. Owned by the caller; release with
* oaknode_project_free().
* @brief Reference-counted handle to a project (olive::Project).
*
* Semantics are shared_ptr-like: oaknode_project_init() returns a handle
* whose underlying object has reference count 1, addref(ctx) takes another
* reference, and release(ctx) (or oaknode_project_free()) drops one; the
* project and every node it owns are destroyed when the count reaches zero.
*/
typedef struct OakNodeProject OakNodeProject;
typedef struct OakNodeProject {
void *ctx; /**< Opaque pointer to the reference-counted object. */
void (*addref)(void *ctx); /**< Atomically increments the count. */
void (*release)(void *ctx); /**< Decrements the count, destroys at 0. */
uint32_t abi_version; /**< OAKNODE_ABI_VERSION. */
} OakNodeProject;
/**
* @brief Opaque node handle (defined by the node family; forward-declared
* @brief Node handle (defined by the node family; forward-declared
* here so the headers can be included in any order).
*/
typedef struct OakNodeNode OakNodeNode;
/**
* @brief Opaque folder handle (defined in node/folder.h; forward-declared
* here so the headers can be included in any order). Borrowed from the
* owning project.
* @brief Folder handle (defined in node/folder.h; forward-declared
* here so the headers can be included in any order). Handles obtained from
* a project are borrowed from it.
*/
typedef struct OakNodeFolder OakNodeFolder;
@@ -74,12 +86,16 @@ typedef struct OakNodeFolder OakNodeFolder;
* The project has no root folder until oaknode_project_initialize() is
* called (mirrors Project::initialize()).
*
* @return Project handle, or NULL on allocation failure.
* @return Project handle with reference count 1 (release with
* oaknode_project_free()); ctx is NULL on allocation failure.
*/
OakNodeProject *oaknode_project_init(void);
OakNodeProject oaknode_project_init(void);
/**
* @brief Destroy a project and every node it owns. NULL is a no-op.
* @brief Release one reference to a project handle.
*
* Destroys the project and every node it owns when the count reaches zero.
* NULL handle or NULL ctx is a no-op; clears `project->ctx` after releasing.
*/
void oaknode_project_free(OakNodeProject *project);
@@ -88,7 +104,7 @@ void oaknode_project_free(OakNodeProject *project);
*
* @return OAKNODE_OK, or OAKNODE_E_STATE if already initialized.
*/
int oaknode_project_initialize(OakNodeProject *project);
int oaknode_project_initialize(OakNodeProject project);
/**
* @brief Destructively destroy all nodes in the graph (Project::clear()).
@@ -98,14 +114,16 @@ int oaknode_project_initialize(OakNodeProject *project);
*
* @return OAKNODE_OK or a negative OAKNODE_E_* error code.
*/
int oaknode_project_clear(OakNodeProject *project);
int oaknode_project_clear(OakNodeProject project);
/**
* @brief Borrowed handle of the project's root folder (Project::root()).
*
* NULL if the project has not been initialized.
* The returned handle only releases the handle itself; the project owns the
* folder. Empty handle (ctx == NULL) if the project has not been
* initialized.
*/
OakNodeFolder *oaknode_project_root(OakNodeProject *project);
OakNodeFolder oaknode_project_root(OakNodeProject project);
/**
* @brief Project display name (Project::name(): the filename's base name, or
@@ -114,20 +132,20 @@ OakNodeFolder *oaknode_project_root(OakNodeProject *project);
* @return Required buffer size in bytes including the NUL, or a negative
* OAKNODE_E_* error code.
*/
int oaknode_project_name(const OakNodeProject *project, char *buf, int buf_size);
int oaknode_project_name(OakNodeProject project, char *buf, int buf_size);
/**
* @brief Full path the project was saved as, or "" if untitled
* (Project::filename()). Two-stage string getter.
*/
int oaknode_project_filename(const OakNodeProject *project, char *buf,
int oaknode_project_filename(OakNodeProject project, char *buf,
int buf_size);
/**
* @brief Display name safe for window titles (Project::pretty_filename()).
* Two-stage string getter.
*/
int oaknode_project_pretty_filename(const OakNodeProject *project, char *buf,
int oaknode_project_pretty_filename(OakNodeProject project, char *buf,
int buf_size);
/**
@@ -135,46 +153,47 @@ int oaknode_project_pretty_filename(const OakNodeProject *project, char *buf,
*
* @return OAKNODE_OK or a negative OAKNODE_E_* error code.
*/
int oaknode_project_set_filename(OakNodeProject *project, const char *filename);
int oaknode_project_set_filename(OakNodeProject project, const char *filename);
/**
* @brief 1 if the project has unsaved changes, 0 otherwise
* (Project::is_modified()). Negative OAKNODE_E_* code on NULL.
* (Project::is_modified()). Negative OAKNODE_E_* code on an empty handle.
*/
int oaknode_project_is_modified(const OakNodeProject *project);
int oaknode_project_is_modified(OakNodeProject project);
/**
* @brief Set the modified flag (Project::set_modified()).
*
* @return OAKNODE_OK or a negative OAKNODE_E_* error code.
*/
int oaknode_project_set_modified(OakNodeProject *project, int modified);
int oaknode_project_set_modified(OakNodeProject project, int modified);
/**
* @brief 1 if the project is new (untitled and unmodified, Project::is_new()).
* Negative OAKNODE_E_* code on NULL.
* Negative OAKNODE_E_* code on an empty handle.
*/
int oaknode_project_is_new(const OakNodeProject *project);
int oaknode_project_is_new(OakNodeProject project);
/**
* @brief Effective cache directory (Project::cache_path(), honoring the cache
* location setting). Two-stage string getter.
*/
int oaknode_project_cache_path(const OakNodeProject *project, char *buf,
int oaknode_project_cache_path(OakNodeProject project, char *buf,
int buf_size);
/**
* @brief Copy all project settings (Project::copy_settings()).
*/
int oaknode_project_copy_settings(OakNodeProject *dst,
const OakNodeProject *src);
int oaknode_project_copy_settings(OakNodeProject dst,
OakNodeProject src);
/**
* @brief Cache location setting enum value
* (Project::get_cache_location_setting(): 0 = default location,
* 1 = alongside project, 2 = custom path). Negative OAKNODE_E_* code on NULL.
* 1 = alongside project, 2 = custom path). Negative OAKNODE_E_* code on an
* empty handle.
*/
int oaknode_project_get_cache_location_setting(const OakNodeProject *project);
int oaknode_project_get_cache_location_setting(OakNodeProject project);
/**
* @brief Set the cache location setting (0/1/2, see
@@ -182,14 +201,14 @@ int oaknode_project_get_cache_location_setting(const OakNodeProject *project);
*
* @return OAKNODE_OK or a negative OAKNODE_E_* error code.
*/
int oaknode_project_set_cache_location_setting(OakNodeProject *project,
int oaknode_project_set_cache_location_setting(OakNodeProject project,
int setting);
/**
* @brief Custom cache directory, or "" when none is set
* (Project::get_custom_cache_path()). Two-stage string getter.
*/
int oaknode_project_get_custom_cache_path(const OakNodeProject *project,
int oaknode_project_get_custom_cache_path(OakNodeProject project,
char *buf, int buf_size);
/**
@@ -198,22 +217,25 @@ int oaknode_project_get_custom_cache_path(const OakNodeProject *project,
*
* @return OAKNODE_OK or a negative OAKNODE_E_* error code.
*/
int oaknode_project_set_custom_cache_path(OakNodeProject *project,
int oaknode_project_set_custom_cache_path(OakNodeProject project,
const char *path);
/**
* @brief Project UUID string (Project::get_uuid()). Two-stage string getter.
*/
int oaknode_project_get_uuid(const OakNodeProject *project, char *buf,
int oaknode_project_get_uuid(OakNodeProject project, char *buf,
int buf_size);
/**
* @brief Add a node to the graph; the project takes ownership
* @brief Add a node to the graph; the graph assumes the node's lifetime
* (Project::add_node()).
*
* After a successful call the graph owns the node: releasing `node` only
* releases the handle itself.
*
* @return OAKNODE_OK or a negative OAKNODE_E_* error code.
*/
int oaknode_project_add_node(OakNodeProject *project, OakNodeNode *node);
int oaknode_project_add_node(OakNodeProject project, OakNodeNode node);
/**
* @brief Detach a node from the graph without deleting it
@@ -222,19 +244,21 @@ int oaknode_project_add_node(OakNodeProject *project, OakNodeNode *node);
* @return OAKNODE_OK, OAKNODE_E_NOT_FOUND if the node is not in the graph, or
* another negative OAKNODE_E_* error code.
*/
int oaknode_project_remove_node(OakNodeProject *project, OakNodeNode *node);
int oaknode_project_remove_node(OakNodeProject project, OakNodeNode node);
/**
* @brief Number of nodes belonging to the graph (Project::nodes().size()).
* Negative OAKNODE_E_* code on NULL.
* Negative OAKNODE_E_* code on an empty handle.
*/
int oaknode_project_node_count(const OakNodeProject *project);
int oaknode_project_node_count(OakNodeProject project);
/**
* @brief Borrowed handle of the graph node at `index`, or NULL when out of
* range.
* @brief Borrowed handle of the graph node at `index`.
*
* The returned handle only releases the handle itself. Empty handle
* (ctx == NULL) when out of range.
*/
OakNodeNode *oaknode_project_node_at(const OakNodeProject *project, int index);
OakNodeNode oaknode_project_node_at(OakNodeProject project, int index);
#ifdef __cplusplus
}