From dev-return-1272-archive-asf-public=cust-asf.ponee.io@celix.apache.org Tue May 29 21:54:39 2018 Return-Path: X-Original-To: archive-asf-public@cust-asf.ponee.io Delivered-To: archive-asf-public@cust-asf.ponee.io Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by mx-eu-01.ponee.io (Postfix) with SMTP id A45FF180648 for ; Tue, 29 May 2018 21:54:38 +0200 (CEST) Received: (qmail 65677 invoked by uid 500); 29 May 2018 19:54:37 -0000 Mailing-List: contact dev-help@celix.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@celix.apache.org Delivered-To: mailing list dev@celix.apache.org Received: (qmail 65665 invoked by uid 99); 29 May 2018 19:54:36 -0000 Received: from pnap-us-west-generic-nat.apache.org (HELO spamd3-us-west.apache.org) (209.188.14.142) by apache.org (qpsmtpd/0.29) with ESMTP; Tue, 29 May 2018 19:54:36 +0000 Received: from localhost (localhost [127.0.0.1]) by spamd3-us-west.apache.org (ASF Mail Server at spamd3-us-west.apache.org) with ESMTP id 96F85180336 for ; Tue, 29 May 2018 19:54:36 +0000 (UTC) X-Virus-Scanned: Debian amavisd-new at spamd3-us-west.apache.org X-Spam-Flag: NO X-Spam-Score: 2.129 X-Spam-Level: ** X-Spam-Status: No, score=2.129 tagged_above=-999 required=6.31 tests=[DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, HTML_MESSAGE=2, KAM_LOTSOFHASH=0.25, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H3=-0.01, RCVD_IN_MSPIKE_WL=-0.01, SPF_PASS=-0.001] autolearn=disabled Authentication-Results: spamd3-us-west.apache.org (amavisd-new); dkim=pass (2048-bit key) header.d=gmail.com Received: from mx1-lw-eu.apache.org ([10.40.0.8]) by localhost (spamd3-us-west.apache.org [10.40.0.10]) (amavisd-new, port 10024) with ESMTP id JqmyAzGa5iKs for ; Tue, 29 May 2018 19:54:32 +0000 (UTC) Received: from mail-it0-f43.google.com (mail-it0-f43.google.com [209.85.214.43]) by mx1-lw-eu.apache.org (ASF Mail Server at mx1-lw-eu.apache.org) with ESMTPS id C7B665F11F for ; Tue, 29 May 2018 19:54:31 +0000 (UTC) Received: by mail-it0-f43.google.com with SMTP id y189-v6so19970285itb.2 for ; Tue, 29 May 2018 12:54:31 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=mime-version:from:date:message-id:subject:to; bh=t7xjr8IYHRNGVjX9DgMtDh19PEmVtcqjThD9tMosItI=; b=mH1HBUIYQ0va53kBbysJZMsLj3JoMP76DPSSbo4oZEEcns6+fPAEQ8y95crMhO8Hkl rw4W7smUDFHwNrFfKQdpBK588SJIHMp+Izd3il1VRKQ4PYPOjihyXYf74TNc7bSppTOc xqpTmm3sSmyAOKtYP6d7G6s0D3WeGOSuvVvisdxzsloqAd4poi7O7lpF1yTBSq8z69qB VvDL75TZabQvhvcsJMskwIvZlfveHY6qEocFIvIOc9pwJhGrwVUSG9/fG/mbHcLHLw3H 1bUeN7w2PYoUDZYfh9u0tYPKzAursZf9nvzQU9ExncslL6aqxshWxkduLZE2AhqR5qGP P9SA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:mime-version:from:date:message-id:subject:to; bh=t7xjr8IYHRNGVjX9DgMtDh19PEmVtcqjThD9tMosItI=; b=ngT0KsozjL1sJlGmSM+OE9ienZSBLUEpTy7mwTcpOWGs2YL1o+3ZU7H/ObdAMRaFW6 bnSer29Q9S9FRPv8sx4LdPH2AHSyU/RxwllmwjzRhZLrQhOniMIDh5hP4Z+xdxw3/JHG 0Ne3TWPYqyoTYKRdBDkYt8oDrVvbmpWePxS/MpXd8cPHdX02X/Rnyc4eHj0Zoj8YAHkw 8Rzu3hRFFSNBFL9TuveK8TH2NCpZOf2N8/prNxje7MG2zrgHlBVtm0mcZIshmicbXy/e Z4Kln56LaGoOGfU+i1IIr46k8Go+qBVKC6QudbCQszZ/6NM0c3y+5ccEjhW+KxrhblG/ RJeA== X-Gm-Message-State: ALKqPwePG/mUkAD1dTiGM04YY5i1fKzewNNTyQbClosIWrm7z2DqrtVe JRwHSQPVO4NoAQLE9jqjihIGCY3Fux2c44rJLMhi6A== X-Google-Smtp-Source: ADUXVKLL08rD0ysONFs0VAFdRhRbhkfylZC1mG5F+na7qR6cMIp9t1huFhjzsxouV1PfqDJQh+Hi3dMrWb3JS9lTLwI= X-Received: by 2002:a24:4151:: with SMTP id x78-v6mr293498ita.0.1527623663840; Tue, 29 May 2018 12:54:23 -0700 (PDT) MIME-Version: 1.0 From: Pepijn Noltes Date: Tue, 29 May 2018 21:54:12 +0200 Message-ID: Subject: [DISCUSS] new Celix API To: "dev@celix.apache.org" Content-Type: multipart/alternative; boundary="000000000000d57418056d5d9919" --000000000000d57418056d5d9919 Content-Type: text/plain; charset="UTF-8" Hi All, A while ago I created a proposal for a v3 Celix API. Since a few week I have started working on some of the the changes, but adjusted them to keep close to the OSGI api/nomenclature. In this thread I would like to explain the changes I made and hope to start a discussion to see if these change are in line with that we want as a Celix community. The API changes are added in new headers so that a) they can coexist with the current API and b) the headers are not cluttered with two different styles of API. The basis premise is that most of the updated API is centred around the bundle context. The bundle context is (from the OSGI spec) a object that represents the execution context of a single bundle within the OSGi framework, and acts as a proxy to the underlying Framework. And as such should IMO be the primary entry to interact with everything the Celix framework is offering. This for example means that now both register and unregistering service is done through the bundle context, also that setting up and stopping a service tracker is done though the bundle context, etc. Some of the more important changes are: - All the updated APIs are location in the celix_ prefixed headers. - All public functions in the update API are prefixed with celix_. This is of course to prevent symbol collisions. - Explicit locking is prevented by calling useService(s) functions, which accepts user provided callbacks so that the framework can take care of locking/race-conditions during the invocation of the callbacks. Locking is really necessary in Celix to ensure that services cannot be freed/unloaded if that service is still in use. On the other hand exposing explicit lock functions or lock types are ugly, cumbersome and error prone. The updated bundle context API now has useService(s) calls which lets the users provide a callback. In the callback the framework ensure the locking and the user can safely use the service - and other arguments - during the callback. - More focus on const correctness, specifically in the tracker/use callbacks. - Simpler error reporting. Although always returning a int stating if a error occurred is very clear, it does make the code more verbose and (IMO) unnatural to read. In most cases the returning type can easily be used to indicate an error. This is now more often used. - Less use of pointers. E.g. registering a service now returns a service id (or <0 if error) instead of a service_registration_t pointer and setting up a service tracker now return a tracker id (long). This prevents dangling pointers and reduces the public api. - Most of the bundle context calls now have a simple call (e.g. celix_bundleContext_registerService) with a few arguments and a more complex call which accepts a pointer to a options struct (e.g. celix_bundleContext_registerServiceWithOptions). This ensure that the basic use can be left simple and also ensure that more complex setup are still readable. For example something like: celix_bundleContext_registerServiceComplex(ctx, "service name", NULL, NULL, props, NULL, "1.2.0"); Can be written as: celix_service_registrations_options_t opts = CELIX_EMPTY_SERVICE_REGISTRATION_OPTIONS; opts.serviceName = "servicename"; opts.properties = props; opts.serviceLanguage = lang; celix_bundleContext_registerServiceWithOptions(ctx, &opts); More verbose, but also more readable. With the additional benefit that these options struct can be extended in a (source level) backwards manner. - Although not a change, but IMO a benefit: Documenting the bundle context API should help a lot in making the Celix framework more easier to understand and get started with Celix. For the code and updated examples see: - celix_bundle_context.h https://github.com/apache/celix/blob/3e27acf533a195132934a3a5d6935c95f47c7ea9/libs/framework/include/celix_bundle_context.h - C bundle example https://github.com/apache/celix/tree/3e27acf533a195132934a3a5d6935c95f47c7ea9/examples/celix-examples/bundle_example_c - C services example https://github.com/apache/celix/tree/3e27acf533a195132934a3a5d6935c95f47c7ea9/examples/celix-examples/services_example_c Some work is also already done for a C++ api. This is currently a fully header based implementation, meaning that the installed celix libraries can be kept pure C, but user can choose to create bundles in C++. Note that there are still a lot of TODO and the API is not stable. For more info see: - C++ BundleContext https://github.com/apache/celix/blob/be6612f0f259cf080fe5ca1f6fbbfa9bb61a502c/libs/framework/include/celix/BundleContext.h - C++ bundle example https://github.com/apache/celix/tree/be6612f0f259cf080fe5ca1f6fbbfa9bb61a502c/examples/celix-examples/bundle_example_cxx - C++ services example https://github.com/apache/celix/tree/be6612f0f259cf080fe5ca1f6fbbfa9bb61a502c/examples/celix-examples/services_example_cxx All in all my hope it that this simplifies to usage of Celix, but at the same time ensure that we can still support the "old" API for the foreseeable future. Any though, comments or no-dont-do-this remarks are welcome. Greetings, Pepijn --000000000000d57418056d5d9919--