DOC: conn-stream: Add comments on functions of the new CS api
With the conn-stream refactoring, new functions were added. This patch adds
missing comments to help devs to use them.
diff --git a/include/haproxy/conn_stream-t.h b/include/haproxy/conn_stream-t.h
index 3981fcb..9c5ccfb 100644
--- a/include/haproxy/conn_stream-t.h
+++ b/include/haproxy/conn_stream-t.h
@@ -146,6 +146,18 @@
};
+/* cs_endpoint is the link between the conn-stream and the endpoint (mux or
+ * appctx). It is created by the mux/applet on the client side and share with
+ * the conn-stream. On the server side, it is the opposite. A cs-endpoint
+ * without conn-stream is called an orphan endpoint. A cs-endpoint with no
+ * mux/applet is called a detached endpoint. On detach, the conn-stream
+ * transfers the whole responsibility to the mux/applet and eventually create a
+ * new cs-endpoint (for instance on connection retries).
+ *
+ * <target> is the mux or the appctx
+ * <ctx> is the context set and used by <target>
+ * <flags> CS_EP_*
+*/
struct cs_endpoint {
void *target;
void *ctx;
diff --git a/src/conn_stream.c b/src/conn_stream.c
index 38aaff2..0c6f193 100644
--- a/src/conn_stream.c
+++ b/src/conn_stream.c
@@ -81,7 +81,7 @@
};
-
+/* Initializes an endpoint */
void cs_endpoint_init(struct cs_endpoint *endp)
{
endp->target = NULL;
@@ -89,6 +89,7 @@
endp->flags = CS_EP_NONE;
}
+/* Tries to alloc an endpoint and initialize it. Returns NULL on failure. */
struct cs_endpoint *cs_endpoint_new()
{
struct cs_endpoint *endp;
@@ -101,13 +102,18 @@
return endp;
}
+/* Releases an endpoint. It is the caller responsibility to be sure it is safe
+ * and it is not shared with another entity
+ */
void cs_endpoint_free(struct cs_endpoint *endp)
{
pool_free(pool_head_cs_endpoint, endp);
}
/* Tries to allocate a new conn_stream and initialize its main fields. On
- * failure, nothing is allocated and NULL is returned.
+ * failure, nothing is allocated and NULL is returned. It is an internal
+ * function. The caller must, at least, set the CS_EP_ORPHAN or CS_EP_DETAC§HED
+ * flag.
*/
static struct conn_stream *cs_new(struct cs_endpoint *endp)
{
@@ -129,6 +135,7 @@
cs->wait_event.tasklet = NULL;
cs->wait_event.events = 0;
+ /* If there is no endpoint, allocate a new one now */
if (!endp) {
endp = cs_endpoint_new();
if (unlikely(!endp))
@@ -143,6 +150,10 @@
return NULL;
}
+/* Creates a new conn-stream and its associated stream from a mux. <endp> must be
+ * defined. It returns NULL on error. On success, the new conn-stream is
+ * returned. In this case, CS_EP_ORPHAN flag is removed.
+ */
struct conn_stream *cs_new_from_mux(struct cs_endpoint *endp, struct session *sess, struct buffer *input)
{
struct conn_stream *cs;
@@ -158,6 +169,11 @@
return cs;
}
+/* Creates a new conn-stream and its associated stream from an applet. <endp>
+ * must be defined. It returns NULL on error. On success, the new conn-stream is
+ * returned. In this case, CS_EP_ORPHAN flag is removed. The created CS is used
+ * to set the appctx owner.
+ */
struct conn_stream *cs_new_from_applet(struct cs_endpoint *endp, struct session *sess, struct buffer *input)
{
struct conn_stream *cs;
@@ -175,6 +191,10 @@
return cs;
}
+/* Creates a new conn-stream from an stream. There is no endpoint here, thus it
+ * will be created by cs_new(). So the CS_EP_DETACHED flag is set. It returns
+ * NULL on error. On success, the new conn-stream is returned.
+ */
struct conn_stream *cs_new_from_strm(struct stream *strm, unsigned int flags)
{
struct conn_stream *cs;
@@ -190,6 +210,10 @@
return cs;
}
+/* Creates a new conn-stream from an health-check. There is no endpoint here,
+ * thus it will be created by cs_new(). So the CS_EP_DETACHED flag is set. It
+ * returns NULL on error. On success, the new conn-stream is returned.
+ */
struct conn_stream *cs_new_from_check(struct check *check, unsigned int flags)
{
struct conn_stream *cs;
@@ -204,8 +228,8 @@
return cs;
}
-/* Releases a conn_stream previously allocated by cs_new(), as well as any
- * buffer it would still hold.
+/* Releases a conn_stream previously allocated by cs_new(), as well as its
+ * endpoint, if it exists. This function is called internally or on error path.
*/
void cs_free(struct conn_stream *cs)
{
@@ -221,7 +245,10 @@
}
-/* Attaches a conn_stream to an mux endpoint and sets the endpoint ctx */
+/* Attaches a conn_stream to a mux endpoint and sets the endpoint ctx. Returns
+ * -1 on error and 0 on sucess. CS_EP_DETACHED flag is removed. This function is
+ * called from a mux when it is attached to a stream or a health-check.
+ */
int cs_attach_mux(struct conn_stream *cs, void *target, void *ctx)
{
struct connection *conn = ctx;
@@ -250,7 +277,11 @@
return 0;
}
-/* Attaches a conn_stream to an applet endpoint and sets the endpoint ctx */
+/* Attaches a conn_stream to an applet endpoint and sets the endpoint
+ * ctx. Returns -1 on error and 0 on sucess. CS_EP_DETACHED flag is
+ * removed. This function is called by a stream when a backend applet is
+ * registered.
+ */
static void cs_attach_applet(struct conn_stream *cs, void *target, void *ctx)
{
struct appctx *appctx = target;
@@ -266,7 +297,11 @@
}
}
-/* Attaches a conn_stream to a app layer and sets the relevant callbacks */
+/* Attaches a conn_stream to a app layer and sets the relevant
+ * callbacks. Returns -1 on error and 0 on success. CS_EP_ORPHAN flag is
+ * removed. This function is called by a stream when it is created to attach it
+ * on the conn-stream on the client side.
+ */
int cs_attach_strm(struct conn_stream *cs, struct stream *strm)
{
cs->app = &strm->obj_type;
@@ -293,11 +328,12 @@
return 0;
}
-/* Detach the conn_stream from the endpoint, if any. For a connecrion, if a mux
- * owns the connection ->detach() callback is called. Otherwise, it means the
- * conn-stream owns the connection. In this case the connection is closed and
- * released. For an applet, the appctx is released. At the end, the conn-stream
- * is not released but some fields a reset.
+/* Detaches the conn_stream from the endpoint, if any. For a connecrion, if a
+ * mux owns the connection ->detach() callback is called. Otherwise, it means
+ * the conn-stream owns the connection. In this case the connection is closed
+ * and released. For an applet, the appctx is released. If still allocated, the
+ * endpoint is reset and flag as detached. If the app layer is also detached,
+ * the conn-stream is released.
*/
void cs_detach_endp(struct conn_stream *cs)
{
@@ -354,6 +390,9 @@
cs_free(cs);
}
+/* Detaches the conn_stream from the app layer. If there is no endpoint attached
+ * to the conn_stream
+ */
void cs_detach_app(struct conn_stream *cs)
{
cs->app = NULL;
@@ -370,6 +409,10 @@
cs_free(cs);
}
+/* Resets the conn-stream endpoint. It happens when the app layer want to renew
+ * its endpoint. For a connection retry for instance. If a mux or an applet is
+ * attached, a new endpoint is created. Returns -1 on error and 0 on sucess.
+ */
int cs_reset_endp(struct conn_stream *cs)
{
struct cs_endpoint *new_endp;