diff options
Diffstat (limited to 'midimonster.h')
| -rw-r--r-- | midimonster.h | 54 |
1 files changed, 26 insertions, 28 deletions
diff --git a/midimonster.h b/midimonster.h index 61467c1..75eb30a 100644 --- a/midimonster.h +++ b/midimonster.h @@ -192,8 +192,8 @@ typedef struct _backend_instance { /* * Instance channel structure - * Backends may either manage their own channel registry - * or use the memory returned by mm_channel() + * Backends may either manage their own channel registry or use the global + * channel store via the mm_channel() API */ typedef struct _backend_channel { instance* instance; @@ -218,25 +218,24 @@ MM_API int mm_backend_register(backend b); /* * Finds an instance matching the specified backend and identifier. - * Since setting an identifier for an instance is optional, - * this may not work depending on the backend. - * Instance identifiers may for example be set in the backends - * mmbackend_start call. + * Since setting an identifier for an instance is optional, this may not work + * depending on the backend. Instance identifiers may for example be set in the + * backends mmbackend_start call. */ MM_API instance* mm_instance_find(char* backend, uint64_t ident); /* - * Provides a pointer to a channel structure, pre-filled with - * the provided instance reference and identifier. - * The `create` parameter is a boolean flag indicating whether - * a channel matching the `ident` parameter should be created if - * none exists. If the instance already registered a channel - * matching `ident`, a pointer to it is returned. - * This API is just a convenience function. The array of channels is - * only used for mapping internally, creating and managing your own - * channel store is possible. When returning pointers from a - * backend-local channel store, the returned pointers must stay - * valid over the lifetime of the instance. + * Provides a pointer to a channel structure, pre-filled with the provided + * instance reference and identifier. + * The `create` parameter is a boolean flag indicating whether a channel + * matching the `ident` parameter should be created in the global channel store + * if none exists yet. If the instance already registered a channel matching + * `ident`, a pointer to the existing channel is returned. + * This API is just a convenience function. Creating and managing a + * backend-internal channel store is possible (and encouraged for performance + * reasons). When returning pointers from a backend-local channel store, the + * returned pointers must stay valid over the lifetime of the instance and + * provide valid `instance` members, as they are used for callbacks. * For each channel with a non-NULL `impl` field registered using * this function, the backend will receive a call to its channel_free * function (if it exists). @@ -244,17 +243,16 @@ MM_API instance* mm_instance_find(char* backend, uint64_t ident); MM_API channel* mm_channel(instance* i, uint64_t ident, uint8_t create); /* - * Register (manage = 1) or unregister (manage = 0) a file descriptor - * to be selected on. The backend will be notified when the descriptor - * becomes ready to read via its registered mmbackend_process_fd call. - * The `impl` argument will be provided within the corresponding - * managed_fd structure upon callback. + * Register (manage = 1) or unregister (manage = 0) a file descriptor to be + * selected on. The backend will be notified when the descriptor becomes ready + * to read via its registered mmbackend_process_fd call. The `impl` argument + * will be provided within the corresponding managed_fd structure upon callback. */ MM_API int mm_manage_fd(int fd, char* backend, int manage, void* impl); /* - * Notifies the core of a channel event. Called by backends to - * inject events gathered from their backing implementation. + * Notifies the core of a channel event. Called by backends to inject events + * gathered from their backing implementation. */ MM_API int mm_channel_event(channel* c, channel_value v); @@ -266,14 +264,14 @@ MM_API int mm_backend_instances(char* backend, size_t* n, instance*** i); /* * Query an internal timestamp, which is updated every core iteration. - * This timestamp should not be used as a performance counter, but can be - * used for timeouting. Resolution is milliseconds. + * This timestamp should not be used as a performance counter, but can be used + * for timeouting. Resolution is milliseconds. */ MM_API uint64_t mm_timestamp(); /* - * Create a channel-to-channel mapping. This API should not - * be used by backends. It is only exported for core modules. + * Create a channel-to-channel mapping. This API should not be used by backends. + * It is only exported for core modules. */ int mm_map_channel(channel* from, channel* to); #endif |