/* coroutine_rpc.h - Simple request/response system for coroutine.{h,c}
 *
 * Copyright (C) 2024  Luke T. Shumaker <lukeshu@lukeshu.com>
 * SPDX-Licence-Identifier: AGPL-3.0-or-later
 */

/**
 * The cr_rpc_* macros form a simple request/response mechanism built
 * on top of the cr_pause_and_yeild() and cr_unpause() primitives.
 */
#ifndef _COROUTINE_RPC_H_
#define _COROUTINE_RPC_H_

#include "coroutine.h"

/**
 * cr_rpc_t(req_t, resp_t) returns the type definition for a
 * rcp-channel on which the requester submits a value of type `req_t`
 * and the responder responds with a value of type `resp_t`.
 *
 * There must only ever be 1 concurrent writer and 1 concurrent
 * reader. If you need 1:n, n:1, or m:n; then you should instead use a
 * series of coroutine_chan.h.
 */
#define cr_rpc_t(req_t, resp_t) struct { \
		cid_t   requester;       \
		cid_t   responder;       \
		req_t  *req_p;           \
		resp_t *resp_p;          \
	}

/* These "functions" are preprocessor macros instead of real C
 * functions so that the compiler can do type-checking instead of
 * having these functions take `void*`.  */ 

/**
 * ch_rpc_req(cr_rpc_t(req_t, resp_t) *ch, resp_t *resp, req_t req)
 * submits the `req` request to `ch` puts the response in `*resp_p`.
 *
 * Blocking: Always; until the responder has called both
 * cr_rpc_recv_req() and cr_rpc_send_resp().
 */
#define cr_rpc_req(ch, _resp_p, _req) do {           \
		(ch)->requester = cr_getcid();       \
		(ch)->req_p = &(_req);               \
		(ch)->resp_p = (_resp_p;             \
		if ((ch)->responder != 0)            \
			cr_unpause((ch)->responder); \
		cr_pause_and_yield();                \
	} while (0)

/**
 * cr_rpc_have_req(cr_rpc_t(req_t, resp_t) *ch) allows a responder
 * to check whether or not there is a request waiting to be received
 * (with cr_rpc_recv_req()) without blocking if there is not.
 *
 * Blocking: Never.
 */
#define cr_rpc_have_req(ch) ((ch)->requester != 0)

/**
 * cr_rpc_recv_req(cr_rpc_t(req_t, resp_t) *ch, req_t *req_p) reads
 * a request from ch into `*req_p`.
 *
 * If there is not a pending request on `ch`, blocks until there is.
 *
 * Blocking: Maybe.
 */
#define cr_rpc_recv_req(ch, _req_p) do {       \
		(ch)->responder = cr_getcid(); \
		if ((ch)->requester == 0)      \
			cr_pause_and_yield();  \
		*(_req_p) = *((ch)->req_p);    \
		(ch)->req_p = NULL;            \
	} while (0)

/**
 * cr_rpc_send_resp(cr_rpc_t(req_t, resp_t) *ch, resp_t resp) sends
 * the reply to the most-recently-read request.
 *
 * Blocking: Never.
 */
#define cr_rpc_send_resp(ch, _resp) do {       \
		cr_unpause((ch)->requester);   \
		(ch)->responder = 0;           \
		(ch)->requester = 0;           \
		*((ch)->resp_p) = (_resp);     \
		(ch)->resp_p = NULL;           \
	} while (0)

#endif /* _COROUTINE_RPC_H_ */