Author: brane
Date: Wed Aug 6 23:47:27 2025
New Revision: 1927654
Log:
Remove the serf_connection_create3() public function. It was added when Serf
did not have an asynchronous DNS resolver and is now functionally replaced
by serf_connection_create_async().
* serf.h
(serf_connection_create3): Removed.
(serf_connection_create,
serf_connection_create2,
serf_connection_create_async,
serf_address_resolve_async): Update the documentation.
* src/outgoing.c
(create_connection): Renamed from serf_connection_create3 and made private.
* src/resolve.c
(serf_address_resolve_async): Ignore proxy configuration, that part is
already handled by serf_connection_create_async.
Modified:
serf/trunk/serf.h
serf/trunk/src/outgoing.c
serf/trunk/src/resolve.c
Modified: serf/trunk/serf.h
==============================================================================
--- serf/trunk/serf.h Wed Aug 6 20:10:02 2025 (r1927653)
+++ serf/trunk/serf.h Wed Aug 6 23:47:27 2025 (r1927654)
@@ -470,15 +470,17 @@ typedef apr_status_t (*serf_credentials_
* destroying this pool will close the connection, and terminate any
* outstanding requests or responses.
*
+ * The @a setup callback will be invoked, and @a setup_baton passed to it,
+ * once the connection is actually established. @see serf_connection_setup_t.
+ *
* When the connection is closed (upon request or because of an error),
* then the @a closed callback is invoked, and @a closed_baton is passed.
*
- * ### doc on setup(_baton). tweak below comment re: acceptor.
- * NULL may be passed for @a acceptor and @a closed; default implementations
+ * NULL may be passed for @a setup and @a closed; default implementations
* will be used.
*
- * @note The connection is not made immediately. It will be opened on
- * the next call to @see serf_context_run.
+ * @note the connection is not made immediately. It will be opened
+ * asynchronously on the next call to serf_context_run().
*/
serf_connection_t *serf_connection_create(
serf_context_t *ctx,
@@ -492,59 +494,37 @@ serf_connection_t *serf_connection_creat
/**
* Create a new connection associated with the @a ctx serf context.
*
- * Like @see serf_connection_create3 but with @a host_address set to @c NULL.
- */
-apr_status_t serf_connection_create2(
- serf_connection_t **conn,
- serf_context_t *ctx,
- apr_uri_t host_info,
- serf_connection_setup_t setup,
- void *setup_baton,
- serf_connection_closed_t closed,
- void *closed_baton,
- apr_pool_t *pool);
-
-
-/**
- * Create a new connection associated with the @a ctx serf context.
- *
* A connection will be created to (eventually) connect to the address
- * specified by @a address. The address must live at least as long as
- * @a pool (thus, as long as the connection object).
- *
- * If @a host_address is @c NULL, the host address will be looked up
- * based on the hostname in @a host_info; otherwise @a host_address
- * will be used to connect and @a host_info will only be used for
- * setting request headers.
+ * specified by @a host_info (either directly or through a proxy), which
+ * must live at least as long as @a pool (thus, as long as the connection
+ * object). The @a host_info will also be used for setting request headers.
*
* The connection object will be allocated within @a pool. Clearing or
* destroying this pool will close the connection, and terminate any
* outstanding requests or responses.
*
+ * The @a setup callback will be invoked, and @a setup_baton passed to it,
+ * once the connection is actually established. @see serf_connection_setup_t.
+ *
* When the connection is closed (upon request or because of an error),
* then the @a closed callback is invoked, and @a closed_baton is passed.
*
- * ### doc on setup(_baton). tweak below comment re: acceptor.
- * NULL may be passed for @a acceptor and @a closed; default implementations
+ * NULL may be passed for @a setup and @a closed; default implementations
* will be used.
*
- * @note the connection is not made immediately. It will be opened on
- * the next call to @see serf_context_run.
- *
- * @since New in 1.4.
+ * @note The connection is not made immediately. It will be opened
+ * asynchronously on the next call to serf_context_run().
*/
-apr_status_t serf_connection_create3(
+apr_status_t serf_connection_create2(
serf_connection_t **conn,
serf_context_t *ctx,
apr_uri_t host_info,
- apr_sockaddr_t *host_address,
serf_connection_setup_t setup,
void *setup_baton,
serf_connection_closed_t closed,
void *closed_baton,
apr_pool_t *pool);
-
/**
* Notification callback when an address hae been resolved.
*
@@ -574,8 +554,11 @@ typedef void (*serf_address_resolved_t)(
* Asynchronously resolve an address.
*
* The address represented by @a host_info is intended to be used to create
- * new connections in @a ctx; proxy configuration will be taken into account
- * during resolution. See, for example, serf_connection_create3().
+ * new connections in @a ctx; see, for example, serf_connection_create().
+ * However, unlike in the connection creation functions, the address will be
+ * resolved regardless of proxy configuration. In order to avoid unnecessary
+ * address resolution, use serf_connection_create_async(), which does take
+ * proxy configuration into account.
*
* The @a resolve callback will be called during a subsequent call to
* serf_context_run() or serf_context_prerun() and will receive the same
@@ -625,14 +608,15 @@ typedef void (*serf_connection_created_t
* Asyncchronously create a new connection associated with
* the @a ctx serf context.
*
- * Like serf_connection_create3() with @a host_address set to @c NULL,
- * except that address resolution is performed asynchronously, similarly to
- * serf_address_resolve_async().
+ * Like serf_connection_create2() except that address resolution is performed
+ * asynchronously, similarly to serf_address_resolve_async(). Address
resolution
+ * will be skipped if a proxy is configured; in this case, the function becomes
+ * synchronous and effectively equivalent to serf_connection_create2().
*
* The @a created callback with @a created_baton is called when the connection
* is created but before it is opened. Note that depending on the configuration
- * of @a ctx,the connection may be created and this callback be invoked
- * synchronously during the scope of this function call.
+ * of @a ctx and @a host_info, the connection may be created and this callback
+ * be invoked synchronously during the scope of this function call.
*
* @since New in 1.4.
*/
@@ -1040,8 +1024,8 @@ serf_bucket_t *serf_context_bucket_socke
* settings.
*
* This function will set following header(s):
- * - Host: if the connection was created with @see serf_connection_create2
- * or @see serf_connection_create3
+ * - Host: if the connection was created serf_connection_create2()
+ * or serf_connection_create_async()
*/
serf_bucket_t *serf_request_bucket_request_create(
serf_request_t *request,
Modified: serf/trunk/src/outgoing.c
==============================================================================
--- serf/trunk/src/outgoing.c Wed Aug 6 20:10:02 2025 (r1927653)
+++ serf/trunk/src/outgoing.c Wed Aug 6 23:47:27 2025 (r1927654)
@@ -1278,33 +1278,15 @@ serf_connection_t *serf_connection_creat
return conn;
}
-apr_status_t serf_connection_create2(
- serf_connection_t **conn,
- serf_context_t *ctx,
- apr_uri_t host_info,
- serf_connection_setup_t setup,
- void *setup_baton,
- serf_connection_closed_t closed,
- void *closed_baton,
- apr_pool_t *pool)
-{
- return serf_connection_create3(conn, ctx, host_info, NULL,
- setup, setup_baton,
- closed, closed_baton,
- pool);
-}
-
-
-apr_status_t serf_connection_create3(
- serf_connection_t **conn,
- serf_context_t *ctx,
- apr_uri_t host_info,
- apr_sockaddr_t *host_address,
- serf_connection_setup_t setup,
- void *setup_baton,
- serf_connection_closed_t closed,
- void *closed_baton,
- apr_pool_t *pool)
+static apr_status_t create_connection(serf_connection_t **conn,
+ serf_context_t *ctx,
+ apr_uri_t host_info,
+ apr_sockaddr_t *host_address,
+ serf_connection_setup_t setup,
+ void *setup_baton,
+ serf_connection_closed_t closed,
+ void *closed_baton,
+ apr_pool_t *pool)
{
apr_status_t status = APR_SUCCESS;
serf_config_t *config;
@@ -1362,6 +1344,22 @@ apr_status_t serf_connection_create3(
return status;
}
+apr_status_t serf_connection_create2(
+ serf_connection_t **conn,
+ serf_context_t *ctx,
+ apr_uri_t host_info,
+ serf_connection_setup_t setup,
+ void *setup_baton,
+ serf_connection_closed_t closed,
+ void *closed_baton,
+ apr_pool_t *pool)
+{
+ return create_connection(conn, ctx, host_info, NULL,
+ setup, setup_baton,
+ closed, closed_baton,
+ pool);
+}
+
struct async_create_baton
{
@@ -1391,12 +1389,12 @@ static void async_conn_create(serf_conte
baton->conn_pool);
}
if (status == APR_SUCCESS) {
- status = serf_connection_create3(&conn, ctx,
- baton->host_info,
- host_address,
- baton->setup, baton->setup_baton,
- baton->closed,
baton->closed_baton,
- baton->conn_pool);
+ status = create_connection(&conn, ctx,
+ baton->host_info,
+ host_address,
+ baton->setup, baton->setup_baton,
+ baton->closed, baton->closed_baton,
+ baton->conn_pool);
}
}
@@ -1421,14 +1419,14 @@ apr_status_t serf_connection_create_asyn
if (ctx->proxy_address)
{
/* If we're using a proxy, we do *not* resolve the host
- (see serf_connection_create3(), above), so just create
+ (see create_connection(), above), so just create
the connection immediately. */
serf_connection_t *conn;
- status = serf_connection_create3(&conn, ctx,
- host_info, NULL,
- setup, setup_baton,
- closed, closed_baton,
- pool);
+ status = create_connection(&conn, ctx,
+ host_info, NULL,
+ setup, setup_baton,
+ closed, closed_baton,
+ pool);
if (status == APR_SUCCESS)
created(ctx, created_baton, conn, status, scratch_pool);
}
Modified: serf/trunk/src/resolve.c
==============================================================================
--- serf/trunk/src/resolve.c Wed Aug 6 20:10:02 2025 (r1927653)
+++ serf/trunk/src/resolve.c Wed Aug 6 23:47:27 2025 (r1927654)
@@ -108,16 +108,6 @@ apr_status_t serf_address_resolve_async(
}
apr_pool_create(&resolve_pool, ctx->pool);
-
- /* See serf_connection_create3(): if there's a proxy configured in the
- context, don't resolve the host address, just register the result. */
- if (ctx->proxy_address)
- {
- push_resolve_result(ctx, NULL, APR_SUCCESS,
- resolved, resolved_baton, resolve_pool);
- return APR_SUCCESS;
- }
-
return resolve_address_async(ctx, host_info, resolved, resolved_baton,
resolve_pool, pool);
}
