Commit e4741682 authored by Dominik Charousset's avatar Dominik Charousset

Fine-tune migration guide for 0.9 => 0.10

parent 2dde519e
...@@ -129,21 +129,26 @@ Typed actors can now be published in the network and also use all operations unt ...@@ -129,21 +129,26 @@ Typed actors can now be published in the network and also use all operations unt
\clearpage \clearpage
\subsubsection{0.9 $\Rightarrow$ 0.10 (\texttt{libcppa} $\Rightarrow$ \texttt{libcaf})} \subsubsection{0.9 $\Rightarrow$ 0.10 (\texttt{libcppa} $\Rightarrow$ \texttt{libcaf})}
With the first release under the name \texttt{libcaf}, we have redesigned several parts of the library. The first release under the new name \texttt{libcaf} is an overhaul of the entire library.
Some classes have been renamed or relocated, others have been removed. Some classes have been renamed or relocated, others have been removed.
The purpose of this refactoring was to make the library easier to grasp and to make its API more consistent. The purpose of this refactoring was to make the library easier to grasp and to make its API more consistent.
All classes now live in the namespace \lstinline^caf^ and all headers have the top level folder ``caf'' instead of ``cppa''. All classes now live in the namespace \lstinline^caf^ and all headers have the top level folder ``caf'' instead of ``cppa''.
For example, \lstinline^#include "cppa/actor.hpp"^ becomes \lstinline^#include "caf/actor.hpp"^. For example, \lstinline^#include "cppa/actor.hpp"^ becomes \lstinline^#include "caf/actor.hpp"^.
Further, the convenience header to get all parts of the user API is now \lstinline^"caf/all.hpp"^.
To give developers more time to migrate their code and to not break existing code right away, the header \lstinline^cppa/cppa.hpp^ still exists and defines the namespace \lstinline^cppa^ as an alias for \lstinline^caf^. The networking has been separated from the core library.
Furthermore, it provides implementations or type aliases for deprecated or renamed classes. To get the networking components, simply include \lstinline^"caf/io/all.hpp"^ and use the namespace \lstinline^caf::io^, e.g., \lstinline^caf::io::remote_actor^.
You won't get any warning about deprecated code with 0.10.
However, we will add these warnings in the next library version and remove deprecated code eventually. Version 0.10 still includes the header \lstinline^cppa/cppa.hpp^ to make the transition process for users easier and to not break existing code right away.
The header defines the namespace \lstinline^cppa^ as an alias for \lstinline^caf^.
Even when using the backwards compatibility header, there is one breaking change regardless: guard expressions have been removed. Furthermore, it provides implementations or type aliases for renamed or removed classes such as \lstinline^cow_tuple^.
You won't get any warning about deprecated headers with 0.10.
However, we will add this warnings in the next library version and remove deprecated code eventually.
Even when using the backwards compatibility header, the new library has breaking changes.
For instance, guard expressions have been removed entirely.
The reasoning behind this decision is that we already have projections to modify the outcome of a match. The reasoning behind this decision is that we already have projections to modify the outcome of a match.
Guard expressions add little expressive power to the library but a whole lot of code that is hard to maintain due to its complexity. Guard expressions add little expressive power to the library but a whole lot of code that is hard to maintain in the long run due to its complexity.
Using projections to not only perform type conversions but also to restrict values is the natural thing to do. Using projections to not only perform type conversions but also to restrict values is the more natural choice.
The following table summarizes the changes made to the API. The following table summarizes the changes made to the API.
...@@ -154,9 +159,10 @@ The following table summarizes the changes made to the API. ...@@ -154,9 +159,10 @@ The following table summarizes the changes made to the API.
\hline \hline
\lstinline^cow_tuple => X^ & We want to provide a streamlined, simple API. Shipping a full tuple abstraction with the library does not fit into this philosophy. The removal of \lstinline^cow_tuple^ implies the removal of related functions such as \lstinline^tuple_cast^. \\ \lstinline^cow_tuple => X^ & We want to provide a streamlined, simple API. Shipping a full tuple abstraction with the library does not fit into this philosophy. The removal of \lstinline^cow_tuple^ implies the removal of related functions such as \lstinline^tuple_cast^. \\
\hline \hline
\lstinline^cow_ptr => X^ & Again, shipping smart pointer types like these does not fit into our design philosophy. However, messages still have the copy-on-write semantics. \\ \lstinline^cow_ptr => X^ & This pointer class is an implementation detail of \lstinline^message^ and should not live in the global namespace in the first place. It also had the wrong name, because it is intrusive. \\
\hline \hline
\lstinline^X => message_builder^ & This new class can be used to create messages dynamically. For example, the content of a vector can be used to create a message using a series of \lstinline^append^ calls. \\ \lstinline^X => message_builder^ & This new class can be used to create messages dynamically. For example, the content of a vector can be used to create a message using a series of \lstinline^append^ calls. \\
\hline \hline
\lstinline^accept_handle^, \lstinline^connection_handle^, \lstinline^publish^, \lstinline^remote_actor^, \lstinline^max_msg_size^, \lstinline^typed_publish^, \lstinline^typed_remote_actor^, \lstinline^publish_local_groups^, \lstinline^new_connection_msg^, \lstinline^new_data_msg^, \lstinline^connection_closed_msg^, \lstinline^acceptor_closed_msg^ & These classes and functions have no logical reason to live in the global \lstinline^caf^ namespace and have been moved to \lstinline^caf::io^. \\ \lstinline^accept_handle^, \lstinline^connection_handle^, \lstinline^publish^, \lstinline^remote_actor^, \lstinline^max_msg_size^, \lstinline^typed_publish^, \lstinline^typed_remote_actor^, \lstinline^publish_local_groups^, \lstinline^new_connection_msg^, \lstinline^new_data_msg^, \lstinline^connection_closed_msg^, \lstinline^acceptor_closed_msg^ & These classes concern I/O functionality and have thus been moved to \lstinline^caf::io^. \\
\hline
\end{tabular*} \end{tabular*}
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment