Read this first!

Clojure issue tracking now lives at http://dev.clojure.org/jira, and the wiki is at http://dev.clojure.org. These Assembla pages are kept online for historical interest only.

Protocols

This page is a design scratchpad. Please see:

http://clojure.org/protocols

for the current documentation.

There are several motivations for protocols:

Provide a high-performance, dynamic polymorphism construct as an alternative to interfaces
Support the best parts of interfaces
- specification only, no implementation
- a single type can implement multiple protocols
While avoiding some of the drawbacks
- Which interfaces are implemented is a design-time choice of the type author, cannot be extended later (although interface injection might eventually address this)
- implementing an interface creates an isa/instanceof type relationship and hierarchy
Avoid the 'expression problem' by allowing independent extension of the set of types, protocols, and implementations of protocols on types, by different parties
- do so without wrappers/adapters
Support the 90% case of multimethods (single dispatch on type) while providing higher-level abstraction/organization

Basics

A protocol is a named set of named methods and their signatures:

(defprotocol AProtocol
  "A doc string for AProtocol abstraction"
  (bar [a b] "bar docs")
  (baz ([a] [a b] [a b c]) "baz docs"))

No implementations are provided
Docs can be specified for the protocol and the functions
The above yields a set of polymorphic functions and a protocol object
- all are namespace-qualified by the ns enclosing the definition
The resulting functions dispatch on the type of their first argument, and thus must have at least one argument
defprotocol is dynamic, and does not require AOT compilation

defprotocol will automatically generate a corresponding interface, with the same name as the protocol, i.e. given a protocol my.ns/Protocol, an interface my.ns.MyProtocol. The interface will have methods corresponding to the protocol functions, and the protocol will automatically work with instances of the interface.

Note that you do not need to use this interface with deftype or reify, as they support protocols directly:

  (defprotocol P 
    (foo [x]) 
    (bar-me ([x] [x y])))

  (deftype Foo [a b c] [P]
    (foo [x] a)
    (bar-me [x] b)
    (bar-me [x y] (+ c y)))
  
  (bar-me (Foo 1 2 3) 42)

  (foo 
    (let [x 42]
      (reify [P] 
        (foo [this] 17)
        (bar-me [this] x)
        (bar-me [this y] x))))

But a Java client looking to participate in the protocol can do so most efficiently by implementing the protocol-generated interface.

External implementations of the protocol (which are needed when you want a class or deftype not in your control to participate in the protocol) can be provided using the extend construct:

(extend ::AType ;or AClass or AnInterface 
  AProtocol
   {:foo an-existing-fn
    :bar (fn [a b] ...)
    :baz (fn ([a]...) ([a b] ...)...)}
  BProtocol 
    {...} 
  ...)

extend takes a type/class (or interface, see below), a one or more protocol + function map (evaluated) pairs
Note that deftype types are specified using their keyword tags:
- ::MyType or :my.ns/MyType
Will extend the polymorphism of the protocol's methods to call the supplied functions when an AType is provided as the first argument
Function maps are maps of the keywordized method names to ordinary fns
- this facilitates easy reuse of existing fns and maps, for code reuse/mixins without derivation or composition
You can implement a protocol on an interface
- this is primarily to facilitate interop with the host (e.g. Java)
- but opens the door to incidental multiple inheritance of implementation
  - since a class can inherit from more than one interface, both of which implement the protocol
- TBD - how to specify which impl to use
  1. leave unspecified - any should work and have the same semantics
  2. or use prefer system at protocol level
The implementing fn can presume first argument instanceof AType
You can implement a protocol on nil
define default implementation of protocol?
- just use Object?

Protocols are fully reified and will support reflective capabilities.

Note the new convenience macros extend-type, extend-class, and extend-protocol
- If you are providing external definitions inline, these will be more convenient than using extend directly

  (extend-type ::MyType 
    Countable
      (cnt [c] ...)
    Foo
      (bar [x y] ...)
      (baz ([x] ...) ([x y zs] ...)))

  expands into:

  (extend ::MyType
   Countable
     {:cnt (fn [c] ...)}
   Foo
     {:baz (fn ([x] ...) ([x y zs] ...))
      :bar (fn [x y] ...)})

See also: extends?, satisfies?, extenders

Prerelease changes under consideration

Stable name for generated interface
Once deftype/defrecord expose stable named types, remove dynamic type tag support
- only support extend and extend-type
  - rename extend-class to extend-type
- all done
have extends? cover both explicit and derivation-based extension?
- done
enhance protocol caching of non-derived to use class as trigger
- watch for protocol changes or not?
Primitives and other types in protocol sigs, carried over to interface?
Prefers system for protocols?
Variadic protocol fns?
revisit protocols :on existing interfaces

Old ideas/scratchpad

Issues

How much dynamic typing to support, if any?
- Dispatch on class only rules out tag/type-slot systems
- Opening up to tag/type-slot has perf implications
  - raises separate question about support for hierarchy
    - same multiple inheritance problems as interfaces
    - would like to avoid MI

Other ideas

Constraints

Support per-method pre and post conditions at protocol level?

Multiprotocols

These would allow the full power of multimethods, including arbitrary dispatch functions, with the proviso that the set be implemented in terms of the same dispatch value. Note the dispatch fn supplied per method in the protocol def:

(defmultiprotocol AProtocol
  "A doc string for AProtocol abstraction"
  (bar dispatch-fn [a b] "bar docs")
  (baz dispatch-fn ([a] [a b] [a b & c]) "baz docs"))

Implementations of the multiprotocol methods can be provided using the implement construct, note the protocol is implemented in terms of a single dispatch value:

(implement AMultiProtocol adispatchvalue
 {:foo an-existing-fn
  :bar (fn [a b] ...)
  :baz (fn ([a]...) ([a b] ...)...)})