mirror of
https://github.com/apple/pkl.git
synced 2026-08-27 06:04:03 +02:00
Daniel Chao
417c08ae11
* Fix possible SIGSEGV from host process. - Require that the same `pkl_exec_t` be used in the same OS thread; returning meaningful error if this fails * Remove `System.exitProcess(1)` logic in NativeTransport; this would kill the host process too and isn't an appropriate action for a received ProtocolException * Allow multiple calls to pkl_init without pkl_close; this limitation doesn't really make any sense * Prefer calling methods defined in graal_isolate.h, instead of creating the same method via CEntryPoint * Add a CMakeLists.txt so that CLion can follow the code and provide proper diagnostics * Improve doc comments; describe params as either in or out
120 lines
4.1 KiB
C
120 lines
4.1 KiB
C
/*
|
|
* Copyright © 2026 Apple Inc. and the Pkl project authors. All rights reserved.
|
|
*
|
|
* Licensed under the Apache License, Version 2.0 (the "License");
|
|
* you may not use this file except in compliance with the License.
|
|
* You may obtain a copy of the License at
|
|
*
|
|
* https://www.apache.org/licenses/LICENSE-2.0
|
|
*
|
|
* Unless required by applicable law or agreed to in writing, software
|
|
* distributed under the License is distributed on an "AS IS" BASIS,
|
|
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
* See the License for the specific language governing permissions and
|
|
* limitations under the License.
|
|
*/
|
|
// pkl.h
|
|
#ifndef PKL_H
|
|
#define PKL_H
|
|
|
|
#if defined(__cplusplus)
|
|
extern "C" {
|
|
#endif
|
|
|
|
#if defined(_WIN32)
|
|
#define PKL_EXPORT __declspec(dllexport)
|
|
#else
|
|
#define PKL_EXPORT __attribute__((visibility("default")))
|
|
#endif
|
|
|
|
#define PKL_ERR_THREAD 1 /* Called using the same pexec_t but from a different thread */
|
|
#define PKL_ERR_PROTOCOL 2 /* Failed to decode a message */
|
|
|
|
/** Error details that occurred during a method call */
|
|
typedef struct {
|
|
char *message;
|
|
} pkl_error_t;
|
|
|
|
/**
|
|
* Pkl executor instance that manages communication with the Pkl runtime.
|
|
*
|
|
* Instances should be created via `pkl_init` and destroyed via `pkl_close`.
|
|
*
|
|
* All calls using this executor should be synchronized in the same thread.
|
|
*/
|
|
typedef struct __pkl_exec_t pkl_exec_t;
|
|
|
|
/**
|
|
* The callback that gets called when a message is received from Pkl.
|
|
*
|
|
* Messages must be deserialized to Pkl's Message Passing API:
|
|
* https://pkl-lang.org/main/current/bindings-specification/message-passing-api.html
|
|
*
|
|
* @param[in] length The length of the message bytes
|
|
* @param[in] message The message itself
|
|
* @param[in] userData User-defined data passed in from pkl_init.
|
|
*/
|
|
typedef void (*pkl_message_response_handler)(unsigned int length, char *message,
|
|
void *userData);
|
|
|
|
/**
|
|
* Initializes and allocates a Pkl executor, writing it to the slot pointed by `exec`.
|
|
*
|
|
* To clean up resources allocated by the executor, use `pkl_close()`.
|
|
*
|
|
* All calls using this executor should come from the same thread.
|
|
*
|
|
* @param[in] handler The callback that gets called when a message is received from Pkl.
|
|
* @param[in] userData User-defined data that gets passed to handler.
|
|
* @param[out] exec The pointer to write the created pkl_exec_t to.
|
|
* @param[out] error The pointer to write error details to. Can optionally be `NULL`.
|
|
*
|
|
* @return 0 on success, non-zero on failure.
|
|
*/
|
|
PKL_EXPORT int pkl_init(pkl_message_response_handler handler, void *userData,
|
|
pkl_exec_t **exec, pkl_error_t *error);
|
|
|
|
/**
|
|
* Send a message to Pkl, providing the length and a pointer to the first byte.
|
|
*
|
|
* Messages must be serialized according to Pkl's Message Passing API:
|
|
* https://pkl-lang.org/main/current/bindings-specification/message-passing-api.html
|
|
*
|
|
* If a message is incorrectly serialized, returns `PKL_ERR_PROTOCOL`.
|
|
* If called from a different thread than `pkl_exec_t`'s originating thread, returns
|
|
* `PKL_ERR_THREAD`.
|
|
*
|
|
* @param[in] pexec The Pkl executor instance.
|
|
* @param[in] length The length of the message, in bytes.
|
|
* @param[in] message The message to send to Pkl.
|
|
* @param[out] error The pointer to write error details to. Can optionally be `NULL`.
|
|
*
|
|
* @return 0 on success, and non-zero otherwise.
|
|
*/
|
|
PKL_EXPORT int pkl_send_message(const pkl_exec_t *pexec, unsigned int length,
|
|
char *message, pkl_error_t *error);
|
|
|
|
/**
|
|
* Cleans up any resources that were created as part of the `pkl_init` process
|
|
* for our `pkl_exec_t` instance.
|
|
*
|
|
* If called from a different thread than `pkl_exec_t`'s originating thread, returns
|
|
* `PKL_ERR_THREAD`.
|
|
*
|
|
* @param[in] pexec The Pkl executor instance.
|
|
* @param[out] error The pointer to write error details to. Can optionally be `NULL`.
|
|
*
|
|
* @return 0 on success, -1 if `pexec` is `NULL`, and an error code otherwise.
|
|
*/
|
|
PKL_EXPORT int pkl_close(pkl_exec_t *pexec, pkl_error_t *error);
|
|
|
|
/**
|
|
* Returns a null-terminated string indicating Pkl's version.
|
|
*/
|
|
PKL_EXPORT const char* pkl_version();
|
|
|
|
#if defined(__cplusplus)
|
|
}
|
|
#endif
|
|
#endif
|