commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Benedikt Ritter <brit...@apache.org>
Subject Re: [lang] [LANG-1291] Provide annotations to document thread safety.
Date Wed, 19 Apr 2017 05:13:37 GMT
Hm, should we leave out the annotations from 3.6 to have more time for
building consensus? Otherwise this will delay the 3.6 release...

Benedikt

Matt Sicker <boards@gmail.com> schrieb am Mi. 19. Apr. 2017 um 01:33:

> You can work around annotation permissiveness by implementing an annotation
> processor to fail compilations with improper combinations of annotations,
> but I feel that the annotation+enum approach is a lot simpler to enforce.
>
> On 18 April 2017 at 04:40, sebb <sebbaz@gmail.com> wrote:
>
> > I think ThreadingBehavior is very confusing as an enum.
> >
> > I expect enum values to be mutually exclusive, but STATELESS is also
> > IMMUTABLE.
> > And of course IMMUTABLE is SAFE.
> >
> > How do I know which enum to use?
> >
> > I don't think this is a good solution to the potential problem of
> > someone using both @ThreadSafe and @NotThreadsafe.
> >
> >
> >
> > On 18 April 2017 at 07:49, Benedikt Ritter <britter@apache.org> wrote:
> > > Hi,
> > >
> > >> Am 18.04.2017 um 08:46 schrieb Gary Gregory <garydgregory@gmail.com>:
> > >>
> > >> Because if you use multiple annotations, you (or tools) can write
> silly
> > >> things like:
> > >>
> > >> @ThreadSafe
> > >> @NotThreadSafe
> > >> public class Foo {
> > >>   …
> > >> }
> > >
> > > Thank you for the clarification. It makes complete sense to me. Given
> > this reason I’m fine with @Contract.
> > >
> > > Benedikt
> > >
> > >>
> > >> Gary
> > >>
> > >> On Mon, Apr 17, 2017 at 11:27 PM, Benedikt Ritter <britter@apache.org
> >
> > >> wrote:
> > >>
> > >>> Hello Gary,
> > >>>
> > >>> Can you please explain why you think it is better to use a single
> > >>> parameterized annotation over several individual annotations?
> > >>>
> > >>> Thank you!
> > >>> Benedikt
> > >>>
> > >>>> Am 17.04.2017 um 20:54 schrieb ggregory@apache.org:
> > >>>>
> > >>>> Repository: commons-lang
> > >>>> Updated Branches:
> > >>>> refs/heads/master 5242157df -> a5e76ebc4
> > >>>>
> > >>>>
> > >>>> [LANG-1291] Provide annotations to document thread safety.
> > >>>>
> > >>>> Project: http://git-wip-us.apache.org/repos/asf/commons-lang/repo
> > >>>> Commit: http://git-wip-us.apache.org/repos/asf/commons-lang/commit/
> > >>> a5e76ebc
> > >>>> Tree: http://git-wip-us.apache.org/repos/asf/commons-lang/tree/
> > a5e76ebc
> > >>>> Diff: http://git-wip-us.apache.org/repos/asf/commons-lang/diff/
> > a5e76ebc
> > >>>>
> > >>>> Branch: refs/heads/master
> > >>>> Commit: a5e76ebc404d419651c2a25b1a62199de64cccf5
> > >>>> Parents: 5242157
> > >>>> Author: Gary Gregory <garydgregory@gmail.com>
> > >>>> Authored: Mon Apr 17 11:54:04 2017 -0700
> > >>>> Committer: Gary Gregory <garydgregory@gmail.com>
> > >>>> Committed: Mon Apr 17 11:54:04 2017 -0700
> > >>>>
> > >>>> ------------------------------------------------------------
> > ----------
> > >>>> .../lang3/concurrent/annotation/Contract.java   | 50 +++++++++++++++
> > >>>> .../annotation/ThreadingBehavior.java           | 66
> > >>> ++++++++++++++++++++
> > >>>> 2 files changed, 116 insertions(+)
> > >>>> ------------------------------------------------------------
> > ----------
> > >>>>
> > >>>>
> > >>>> http://git-wip-us.apache.org/repos/asf/commons-lang/blob/
> > >>>
> a5e76ebc/src/main/java/org/apache/commons/lang3/concurrent/annotation/
> > >>> Contract.java
> > >>>> ------------------------------------------------------------
> > ----------
> > >>>> diff --git a/src/main/java/org/apache/commons/lang3/concurrent/
> > annotation/Contract.java
> > >>> b/src/main/java/org/apache/commons/lang3/concurrent/
> > >>> annotation/Contract.java
> > >>>> new file mode 100644
> > >>>> index 0000000..e34bb95
> > >>>> --- /dev/null
> > >>>> +++ b/src/main/java/org/apache/commons/lang3/concurrent/
> > >>> annotation/Contract.java
> > >>>> @@ -0,0 +1,50 @@
> > >>>> +/*
> > >>>> + * ============================================================
> > ========
> > >>>> + * Licensed to the Apache Software Foundation (ASF) under one
> > >>>> + * or more contributor license agreements.  See the NOTICE file
> > >>>> + * distributed with this work for additional information
> > >>>> + * regarding copyright ownership.  The ASF licenses this file
> > >>>> + * to you 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
> > >>>> + *
> > >>>> + *   http://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.
> > >>>> + * ============================================================
> > ========
> > >>>> + *
> > >>>> + * This software consists of voluntary contributions made by many
> > >>>> + * individuals on behalf of the Apache Software Foundation.  For
> more
> > >>>> + * information on the Apache Software Foundation, please see
> > >>>> + * <http://www.apache.org/>.
> > >>>> + *
> > >>>> + */
> > >>>> +package org.apache.commons.lang3.concurrent.annotation;
> > >>>> +
> > >>>> +import java.lang.annotation.Documented;
> > >>>> +import java.lang.annotation.ElementType;
> > >>>> +import java.lang.annotation.Retention;
> > >>>> +import java.lang.annotation.RetentionPolicy;
> > >>>> +import java.lang.annotation.Target;
> > >>>> +
> > >>>> +/**
> > >>>> + * This annotation defines behavioral contract enforced at runtime
> by
> > >>> instances of annotated classes.
> > >>>> + */
> > >>>> +@Documented
> > >>>> +@Target(ElementType.TYPE)
> > >>>> +@Retention(RetentionPolicy.CLASS)
> > >>>> +public @interface Contract {
> > >>>> +
> > >>>> +    /**
> > >>>> +     * Defines behavioral contract enforced at runtime by instances
> > of
> > >>> annotated classes.
> > >>>> +     *
> > >>>> +     * @return The behavioral contract enforced at runtime by
> > instances
> > >>> of annotated classes.
> > >>>> +     */
> > >>>> +    ThreadingBehavior threading() default ThreadingBehavior.UNSAFE;
> > >>>> +
> > >>>> +}
> > >>>>
> > >>>> http://git-wip-us.apache.org/repos/asf/commons-lang/blob/
> > >>>
> a5e76ebc/src/main/java/org/apache/commons/lang3/concurrent/annotation/
> > >>> ThreadingBehavior.java
> > >>>> ------------------------------------------------------------
> > ----------
> > >>>> diff --git a/src/main/java/org/apache/commons/lang3/concurrent/
> > >>> annotation/ThreadingBehavior.java b/src/main/java/org/apache/
> > >>> commons/lang3/concurrent/annotation/ThreadingBehavior.java
> > >>>> new file mode 100644
> > >>>> index 0000000..e03b164
> > >>>> --- /dev/null
> > >>>> +++ b/src/main/java/org/apache/commons/lang3/concurrent/
> > >>> annotation/ThreadingBehavior.java
> > >>>> @@ -0,0 +1,66 @@
> > >>>> +/*
> > >>>> + * ============================================================
> > ========
> > >>>> + * Licensed to the Apache Software Foundation (ASF) under one
> > >>>> + * or more contributor license agreements.  See the NOTICE file
> > >>>> + * distributed with this work for additional information
> > >>>> + * regarding copyright ownership.  The ASF licenses this file
> > >>>> + * to you 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
> > >>>> + *
> > >>>> + *   http://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.
> > >>>> + * ============================================================
> > ========
> > >>>> + *
> > >>>> + * This software consists of voluntary contributions made by many
> > >>>> + * individuals on behalf of the Apache Software Foundation.  For
> more
> > >>>> + * information on the Apache Software Foundation, please see
> > >>>> + * <http://www.apache.org/>.
> > >>>> + *
> > >>>> + */
> > >>>> +package org.apache.commons.lang3.concurrent.annotation;
> > >>>> +
> > >>>> +/**
> > >>>> + * Defines types of threading behavior enforced at runtime.
> > >>>> + */
> > >>>> +public enum ThreadingBehavior {
> > >>>> +
> > >>>> +    /**
> > >>>> +     * Instances of classes with the given contract are expected
to
> > be
> > >>> fully immutable and thread-safe.
> > >>>> +     */
> > >>>> +    IMMUTABLE,
> > >>>> +
> > >>>> +    /**
> > >>>> +     * Instances of classes with the given contract are expected
to
> > be
> > >>> immutable if their dependencies injected at
> > >>>> +     * construction time are immutable and are expected to be
> > >>> thread-safe if their dependencies are thread-safe.
> > >>>> +     */
> > >>>> +    IMMUTABLE_CONDITIONAL,
> > >>>> +
> > >>>> +    /**
> > >>>> +     * Instances of classes with the given contract are expected
to
> > >>> maintain no state and to be thread-safe.
> > >>>> +     */
> > >>>> +    STATELESS,
> > >>>> +
> > >>>> +    /**
> > >>>> +     * Instances of classes with the given contract are expected
to
> > be
> > >>> fully thread-safe.
> > >>>> +     */
> > >>>> +    SAFE,
> > >>>> +
> > >>>> +    /**
> > >>>> +     * Instances of classes with the given contract are expected
to
> > be
> > >>> thread-safe if their dependencies injected at
> > >>>> +     * construction time are thread-safe.
> > >>>> +     */
> > >>>> +    SAFE_CONDITIONAL,
> > >>>> +
> > >>>> +    /**
> > >>>> +     * Instances of classes with the given contract are expected
to
> > be
> > >>> non thread-safe.
> > >>>> +     */
> > >>>> +    UNSAFE
> > >>>> +
> > >>>> +}
> > >>>>
> > >>>
> > >>>
> > >>> ---------------------------------------------------------------------
> > >>> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> > >>> For additional commands, e-mail: dev-help@commons.apache.org
> > >>>
> > >>>
> > >>
> > >>
> > >> --
> > >> E-Mail: garydgregory@gmail.com | ggregory@apache.org
> > >> Java Persistence with Hibernate, Second Edition
> > >> <https://www.amazon.com/gp/product/1617290459/ref=as_li_
> > tl?ie=UTF8&camp=1789&creative=9325&creativeASIN=1617290459&
> > linkCode=as2&tag=garygregory-20&linkId=cadb800f39946ec62ea2b1af9fe6a2b8>
> > >>
> > >> <http:////
> ir-na.amazon-adsystem.com/e/ir?t=garygregory-20&l=am2&o=1&a=
> > 1617290459>
> > >> JUnit in Action, Second Edition
> > >> <https://www.amazon.com/gp/product/1935182021/ref=as_li_
> > tl?ie=UTF8&camp=1789&creative=9325&creativeASIN=1935182021&
> >
> linkCode=as2&tag=garygregory-20&linkId=31ecd1f6b6d1eaf8886ac902a24de418%22
> > >
> > >>
> > >> <http:////
> ir-na.amazon-adsystem.com/e/ir?t=garygregory-20&l=am2&o=1&a=
> > 1935182021>
> > >> Spring Batch in Action
> > >> <https://www.amazon.com/gp/product/1935182951/ref=as_li_
> > tl?ie=UTF8&camp=1789&creative=9325&creativeASIN=1935182951&
> > linkCode=%7B%7BlinkCode%7D%7D&tag=garygregory-20&linkId=%7B%
> > 7Blink_id%7D%7D%22%3ESpring+Batch+in+Action>
> > >> <http:////
> ir-na.amazon-adsystem.com/e/ir?t=garygregory-20&l=am2&o=1&a=
> > 1935182951>
> > >> Blog: http://garygregory.wordpress.com
> > >> Home: http://garygregory.com/
> > >> Tweet! http://twitter.com/GaryGregory
> > >
> > >
> > > ---------------------------------------------------------------------
> > > To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> > > For additional commands, e-mail: dev-help@commons.apache.org
> > >
> >
> > ---------------------------------------------------------------------
> > To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> > For additional commands, e-mail: dev-help@commons.apache.org
> >
> >
>
>
> --
> Matt Sicker <boards@gmail.com>
>

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message