Commit 79c5acb1 authored by neverlord's avatar neverlord

documentation

parent a759f53b
......@@ -74,43 +74,72 @@ class actor : public channel
/**
* @brief Forces this actor to subscribe to the group @p what.
*
* The group will be unsubscribed if the actor exits.
* The group will be unsubscribed if the actor finishes execution.
* @param what Group instance that should be joined.
*/
void join(group_ptr& what);
/**
* @brief Forces this actor to leave the group @p what.
* @param what Joined group that should be leaved.
* @note Groups are leaved automatically if the Actor finishes
* execution.
*/
void leave(const group_ptr& what);
/**
* @brief Links this actor to @p other.
* @param other Actor instance that whose execution is coupled to the
* execution of this Actor.
*/
virtual void link_to(intrusive_ptr<actor>& other) = 0;
/**
* @brief Unlinks this actor from @p other.
* @param oter Linked Actor.
* @note Links are automatically removed if the Actor finishes execution.
*/
virtual void unlink_from(intrusive_ptr<actor>& other) = 0;
/**
* @brief Establishes a link relation between this actor and @p other.
* @param other Actor instance that wants to link against this Actor.
* @returns @c true if this actor is running and added @p other to its
* list of linked actors.
* list of linked actors; otherwise @c false.
*/
virtual bool establish_backlink(intrusive_ptr<actor>& other) = 0;
/**
* @brief Removes a link relation between this actor and @p other.
* @param other Actor instance that wants to unlink from this Actor.
* @returns @c true if this actor is running and removed @p other
* from its list of linked actors.
* from its list of linked actors; otherwise @c false.
*/
virtual bool remove_backlink(intrusive_ptr<actor>& other) = 0;
// rvalue support
/**
* @copydoc link_to(intrusive_ptr<actor>&)
* Support for rvalue references.
*/
void link_to(intrusive_ptr<actor>&& other);
/**
* @copydoc unlink_from(intrusive_ptr<actor>&)
* Support for rvalue references.
*/
void unlink_from(intrusive_ptr<actor>&& other);
/**
* @copydoc remove_backlink(intrusive_ptr<actor>&)
* Support for rvalue references.
*/
bool remove_backlink(intrusive_ptr<actor>&& to);
/**
* @copydoc establish_backlink(intrusive_ptr<actor>&)
* Support for rvalue references.
*/
bool establish_backlink(intrusive_ptr<actor>&& to);
/**
......@@ -128,7 +157,8 @@ class actor : public channel
inline process_information_ptr parent_process_ptr() const;
/**
* @brief Get the unique identifier of this actor.
* @brief Gets an integer value that uniquely identifies this Actor in
* the process it's executed in.
* @returns The unique identifier of this actor.
*/
inline std::uint32_t id() const;
......@@ -136,7 +166,7 @@ class actor : public channel
/**
* @brief Get the actor that has the unique identifier @p actor_id.
* @returns A pointer to the requestet actor or @c nullptr if no
* running actor with the ID @p actor_id was found.
* running actor with the ID @p actor_id was found in this process.
*/
static intrusive_ptr<actor> by_id(std::uint32_t actor_id);
......
......@@ -6,6 +6,9 @@
namespace cppa {
/**
* @brief Represents a remote Actor.
*/
class actor_proxy : public detail::abstract_actor<actor>
{
......
......@@ -77,6 +77,11 @@
* @brief This namespace contains utility classes and meta programming
* utilities used by the libcppa implementation.
*
* @namespace cppa::detail
* @brief This namespace contains implementation details. Classes and
* functions of this namespace could change even in minor
* updates of the library and should not be used by outside of libcppa.
*
* @defgroup ReceiveMessages Receive messages
* @brief
*
......@@ -90,19 +95,40 @@ namespace cppa {
/**
* @brief Links the calling actor to @p other.
* @param other An Actor that is related with the calling Actor.
*/
void link(actor_ptr& other);
/**
* @copydoc link(actor_ptr&)
* Support for rvalue references.
*/
void link(actor_ptr&& other);
/**
* @brief Links @p lhs and @p rhs;
* @param lhs First Actor instance.
* @param rhs Second Actor instance.
* @pre <tt>lhs != rhs</tt>
*/
void link(actor_ptr& lhs, actor_ptr& rhs);
// enable link(spawn(...), spawn(...)), etc.
/**
* @copydoc link(actor_ptr&,actor_ptr&)
* Support for rvalue references.
*/
void link(actor_ptr&& lhs, actor_ptr& rhs);
/**
* @copydoc link(actor_ptr&,actor_ptr&)
* Support for rvalue references.
*/
void link(actor_ptr&& lhs, actor_ptr&& rhs);
/**
* @copydoc link(actor_ptr&,actor_ptr&)
* Support for rvalue references.
*/
void link(actor_ptr& lhs, actor_ptr&& rhs);
/**
......@@ -113,11 +139,15 @@ void unlink(actor_ptr& lhs, actor_ptr& rhs);
/**
* @brief Adds a monitor to @p whom.
*
* Sends a ":Down" message if @p whom exited.
* Sends a ":Down" message to the calling Actor if @p whom exited.
* @param whom Actor instance that should be monitored by the calling Actor.
*/
void monitor(actor_ptr& whom);
// enable monitor(spawn(...))
/**
* @copydoc monitor(actor_ptr&)
* Support for rvalue references.
*/
void monitor(actor_ptr&& whom);
/**
......@@ -127,8 +157,10 @@ void monitor(actor_ptr&& whom);
void demonitor(actor_ptr& whom);
/**
* @brief
* @returns
* @brief Gets the @c trap_exit state of the calling Actor.
* @returns @c true if the Actor explicitly handles Exit messages;
* @c false if the Actor uses the default behavior (finish execution
* if an Exit message with non-normal exit reason was received).
*/
inline bool trap_exit()
{
......@@ -136,7 +168,11 @@ inline bool trap_exit()
}
/**
* @brief
* @brief Sets the @c trap_exit state of the calling Actor.
* @param new_value Set this to @c true if you want to explicitly handle Exit
* messages. The default is @c false, causing an Actor to
* finish execution if an Exit message with non-normal
* exit reason was received.
*/
inline void trap_exit(bool new_value)
{
......@@ -145,6 +181,10 @@ inline void trap_exit(bool new_value)
/**
* @brief Spawns a new actor that executes @p what with given arguments.
* @param Hint Hint to the scheduler for the best scheduling strategy.
* @param what Function or functor that the spawned Actor should execute.
* @param args Arguments needed to invoke @p what.
* @returns A pointer to the newly created {@link actor Actor}.
*/
template<scheduling_hint Hint, typename F, typename... Args>
actor_ptr spawn(F&& what, const Args&... args)
......@@ -157,9 +197,12 @@ actor_ptr spawn(F&& what, const Args&... args)
/**
* @brief Alias for <tt>spawn<scheduled>(what, args...)</tt>.
* @param what Function or functor that the spawned Actor should execute.
* @param args Arguments needed to invoke @p what.
* @returns A pointer to the newly created {@link actor Actor}.
*/
template<typename F, typename... Args>
actor_ptr spawn(F&& what, const Args&... args)
inline actor_ptr spawn(F&& what, const Args&... args)
{
return spawn<scheduled>(std::forward<F>(what), args...);
}
......@@ -177,49 +220,94 @@ inline void quit(std::uint32_t reason)
/**
* @brief Receives messages in an endless loop.
*
* Equal to:
* @code
* for (;;) { receive(rules); }
* @endcode
* Semantically equal to: <tt>for (;;) { receive(rules); }</tt>
* @param rules Invoke rules to receive and handle messages.
*/
void receive_loop(invoke_rules& rules);
/**
* @copydoc receive_loop(invoke_rules&)
* Support for invoke rules with timeout.
*/
void receive_loop(timed_invoke_rules& rules);
/**
* @copydoc receive_loop(invoke_rules&)
* Support for rvalue references.
*/
inline void receive_loop(invoke_rules&& rules)
{
invoke_rules tmp(std::move(rules));
receive_loop(tmp);
}
/**
* @copydoc receive_loop(invoke_rules&)
* Support for rvalue references and timeout.
*/
inline void receive_loop(timed_invoke_rules&& rules)
{
timed_invoke_rules tmp(std::move(rules));
receive_loop(tmp);
}
/**
* @brief Receives messages in an endless loop.
*
* This function overload provides a simple way to define a receive loop
* with on-the-fly {@link invoke_rules}.
*
* @b Example:
* @code
* receive_loop(on<int>() >> int_fun, on<float>() >> float_fun);
* @endcode
* @see receive_loop(invoke_rules&)
*/
template<typename Head, typename... Tail>
void receive_loop(invoke_rules&& rules, Head&& head, Tail&&... tail)
void receive_loop(invoke_rules& rules, Head&& head, Tail&&... tail)
{
invoke_rules tmp(std::move(rules));
receive_loop(tmp.splice(std::forward<Head>(head)),
receive_loop(rules.splice(std::forward<Head>(head)),
std::forward<Tail>(tail)...);
}
/**
* @brief Receives messages in an endless loop.
*
* This function overload provides a simple way to define a receive loop
* with on-the-fly {@link invoke_rules}.
*
* @b Example:
* @code
* receive_loop(on<int>() >> int_fun, on<float>() >> float_fun);
* @endcode
* @see receive_loop(invoke_rules&)
*
* Support for rvalue references.
*/
template<typename Head, typename... Tail>
void receive_loop(invoke_rules& rules, Head&& head, Tail&&... tail)
void receive_loop(invoke_rules&& rules, Head&& head, Tail&&... tail)
{
receive_loop(rules.splice(std::forward<Head>(head)),
invoke_rules tmp(std::move(rules));
receive_loop(tmp.splice(std::forward<Head>(head)),
std::forward<Tail>(tail)...);
}
/**
* @brief Receives messages as long as @p stmt returns true.
*
* Equal to:
* Semantically equal to: <tt>while (stmt()) { receive(...); }</tt>.
*
* <b>Usage example:</b>
* @code
* while (stmt()) { receive(...); }
* int i = 0;
* receive_while([&]() { return (++i < 10); })
* (
* on<int>() >> int_fun,
* on<float>() >> float_fun
* );
* @endcode
* @param stmt Lambda expression, functor or function returning a @c bool.
* @returns A functor that takes invoke rules.
*/
template<typename Statement>
detail::receive_while_helper<Statement>
......@@ -233,11 +321,20 @@ receive_while(Statement&& stmt)
/**
* @brief Receives messages until @p stmt returns true.
*
* Equal to:
* Semantically equal to: <tt>do { receive(...); } while (stmt() == false);</tt>
*
* <b>Usage example:</b>
* @code
* do { receive(...); } while (stmt() == false);
* int i = 0;
* do_receive
* (
* on<int>() >> int_fun,
* on<float>() >> float_fun
* )
* .until([&]() { return (++i >= 10); };
* @endcode
* @param args
* @param args Invoke rules to handle received messages.
* @returns A functor providing the @c until function.
*/
template<typename... Args>
detail::do_receive_helper do_receive(Args&&... args)
......@@ -254,6 +351,35 @@ inline const message& last_received()
return self()->mailbox().last_dequeued();
}
#ifdef CPPA_DOCUMENTATION
/**
* @brief Send a message to @p whom.
*
* Sends the tuple <tt>{ arg0, args... }</tt> as a message to @p whom.
* @param whom Receiver of the message.
* @param arg0 First value for the message content.
* @param args Any number of values for the message content.
*/
template<typename Arg0, typename... Args>
void send(channel_ptr& whom, const Arg0& arg0, const Args&... args);
/**
* @brief Send a message to @p whom.
*
* <b>Usage example:</b>
* @code
* self() << make_tuple(1, 2, 3);
* @endcode
*
* Sends the tuple @what as a message to @p whom.
* @param whom Receiver of the message.
* @param what Content of the message.
*/
channel_ptr& operator<<(channel_ptr& whom, const any_tuple& what);
#else
template<class C, typename Arg0, typename... Args>
typename util::enable_if<std::is_base_of<channel, C>, void>::type
send(intrusive_ptr<C>& whom, const Arg0& arg0, const Args&... args)
......@@ -269,7 +395,7 @@ send(intrusive_ptr<C>&& whom, const Arg0& arg0, const Args&... args)
if (tmp) tmp->enqueue(message(self(), whom, arg0, args...));
}
// 'matches' send(self(), ...);
// matches send(self(), ...);
template<typename Arg0, typename... Args>
void send(local_actor* whom, const Arg0& arg0, const Args&... args)
{
......@@ -316,6 +442,13 @@ local_actor* operator<<(local_actor* whom, const any_tuple& what);
// matches self() << make_tuple(...)
local_actor* operator<<(local_actor* whom, any_tuple&& what);
#endif
/**
* @brief Replies to the last received message.
* @param arg0 First value for the message content.
* @param args Any number of values for the message content.
*/
template<typename Arg0, typename... Args>
void reply(const Arg0& arg0, const Args&... args)
{
......@@ -325,7 +458,10 @@ void reply(const Arg0& arg0, const Args&... args)
}
/**
* @brief Send a message that is delayed by @p rel_time.
* @brief Sends a message to @p whom that is delayed by @p rel_time.
* @param whom Receiver of the message.
* @param rel_time Relative time duration to delay the message.
* @param data Any number of values for the message content.
*/
template<typename Duration, typename... Data>
void future_send(actor_ptr whom, const Duration& rel_time, const Data&... data)
......@@ -334,7 +470,9 @@ void future_send(actor_ptr whom, const Duration& rel_time, const Data&... data)
}
/**
*
* @brief Replies to the last received message with @p rel_time delay.
* @param rel_time Relative time duration to delay the message.
* @param data Any number of values for the message content.
*/
template<typename Duration, typename... Data>
void delayed_reply(const Duration& rel_time, const Data&... data)
......@@ -361,13 +499,23 @@ inline void await_all_others_done()
* @brief Publishes @p whom at given @p port.
*
* The connection is automatically closed if the lifetime of @p whom ends.
* @param whom Actor that should be published at given @p port.
* @param port Unused TCP port.
* @throws bind_failure
*/
void publish(actor_ptr& whom, std::uint16_t port);
/**
* @copydoc publish(actor_ptr&,std::uint16_t)
* Support for rvalue references.
*/
void publish(actor_ptr&& whom, std::uint16_t port);
/**
* @brief Establish a new connection to the actor at @p host on given @p port.
* @param host Valid hostname or IP address.
* @param port TCP port.
* @returns A pointer to the proxy instance that represents the remote Actor.
*/
actor_ptr remote_actor(const char* host, std::uint16_t port);
......
......@@ -18,6 +18,9 @@
namespace cppa { namespace detail {
/**
* @brief Implements.
*/
template<class Base>
class abstract_actor : public Base
{
......
......@@ -18,6 +18,9 @@
namespace cppa { namespace detail {
/**
* @brief Represents a thread that was converted to an Actor.
*/
class converted_thread_context : public abstract_actor<local_actor>
{
......
......@@ -7,11 +7,11 @@ template<typename T>
class ref_counted_impl
{
T m_rc;
T m_rc;
ref_counted_impl(const ref_counted_impl&) = delete;
ref_counted_impl(const ref_counted_impl&) = delete;
ref_counted_impl& operator=(const ref_counted_impl&) = delete;
ref_counted_impl& operator=(const ref_counted_impl&) = delete;
public:
......
......@@ -14,6 +14,9 @@ namespace cppa { namespace detail {
class task_scheduler;
/**
* @brief A spawned, scheduled Actor.
*/
class scheduled_actor : public abstract_actor<local_actor>
{
......
......@@ -77,7 +77,7 @@ class group : public channel
/**
* @brief Get the name of this module implementation.
* @returnss The name of this module implementation.
* @returns The name of this module implementation.
* @threadsafe
*/
const std::string& name();
......@@ -93,20 +93,20 @@ class group : public channel
/**
* @brief A string representation of the group identifier.
* @returnss The group identifier as string (e.g. "224.0.0.1" for IPv4
* @returns The group identifier as string (e.g. "224.0.0.1" for IPv4
* multicast or a user-defined string for local groups).
*/
const std::string& identifier() const;
/**
* @brief The name of the module.
* @returnss The module name of this group (e.g. "local").
* @returns The module name of this group (e.g. "local").
*/
const std::string& module_name() const;
/**
* @brief Subscribe @p who to this group.
* @returnss A {@link subscription} object that unsubscribes @p who
* @returns A {@link subscription} object that unsubscribes @p who
* if the lifetime of @p who ends.
*/
virtual subscription subscribe(const channel_ptr& who) = 0;
......
......@@ -49,7 +49,7 @@ class process_information : public ref_counted,
/**
* @brief Returns the proccess_information for the running process.
* @returnss
* @returns
*/
static const intrusive_ptr<process_information>& get();
......
......@@ -56,7 +56,7 @@ void receive(invoke_rules& rules, Head&& head, Tail&&... tail)
/**
* @brief Tries to dequeue the next message from the mailbox.
* @returnss @p true if a messages was dequeued;
* @returns @p true if a messages was dequeued;
* @p false if the mailbox is empty
*/
inline bool try_receive(message& msg)
......@@ -66,7 +66,7 @@ inline bool try_receive(message& msg)
/**
* @brief Tries to dequeue the next message from the mailbox.
* @returnss @p true if a messages was dequeued;
* @returns @p true if a messages was dequeued;
* @p false if the mailbox is empty
*/
inline bool try_receive(invoke_rules& rules)
......
......@@ -17,7 +17,30 @@ namespace cppa {
* Serves the requirements of {@link intrusive_ptr}.
* @relates intrusive_ptr
*/
class ref_counted { };
class ref_counted
{
public:
/**
* @brief Increases reference count by one.
*/
void ref();
/**
* @brief Decreases reference cound by one.
* @returns @p true if there are still references to this object
* (reference count > 0); otherwise @p false.
*/
bool deref();
/**
* @brief Queries if there is exactly one reference.
* @returns @p true if reference count is one; otherwise @p false.
*/
bool unique();
};
#else
......
......@@ -73,7 +73,7 @@ class scheduler
/**
* @brief Informs the scheduler about a hidden (non-actor)
* context that should be counted by await_others_done().
* @returnss An {@link attachable} that the hidden context has to destroy
* @returns An {@link attachable} that the hidden context has to destroy
* if his lifetime ends.
*/
virtual attachable* register_hidden_context();
......@@ -104,7 +104,7 @@ void set_scheduler(scheduler* sched);
/**
* @brief Gets the actual used scheduler implementation.
* @returnss The active scheduler (default constructed).
* @returns The active scheduler (default constructed).
*/
scheduler* get_scheduler();
......
......@@ -104,13 +104,13 @@ class uniform_type_info : cppa::util::comparable<uniform_type_info>
/**
* @brief Get instance by uniform name.
* @param uniform_name The libCPPA internal name for a type.
* @returnss The instance associated to @p uniform_name.
* @returns The instance associated to @p uniform_name.
*/
static uniform_type_info* by_uniform_name(const std::string& uniform_name);
/**
* @brief Get all instances.
* @returnss A vector with all known (announced) instances.
* @returns A vector with all known (announced) instances.
*/
static std::vector<uniform_type_info*> instances();
......@@ -118,13 +118,13 @@ class uniform_type_info : cppa::util::comparable<uniform_type_info>
/**
* @brief Get the internal libCPPA name for this type.
* @returnss A string describing the libCPPA internal type name.
* @returns A string describing the libCPPA internal type name.
*/
inline const std::string& name() const { return m_name; }
/**
* @brief Get the unique identifier of this instance.
* @returnss The unique identifier of this instance.
* @returns The unique identifier of this instance.
*/
inline const identifier& id() const { return m_id; }
......
......@@ -20,7 +20,7 @@ struct abstract_type_list
/**
* @brief Increases the iterator position.
* @returnss @c false if the iterator is at the end; otherwise @c true.
* @returns @c false if the iterator is at the end; otherwise @c true.
*/
virtual bool next() = 0;
......
......@@ -565,7 +565,7 @@ WARN_LOGFILE =
# directories like "/usr/src/myproject". Separate the files or directories
# with spaces.
INPUT = cppa/ cppa/util
INPUT = cppa/ cppa/util cppa/detail
# This tag can be used to specify the character encoding of the source files
# that doxygen parses. Internally doxygen uses the UTF-8 encoding, which is
......
......@@ -24,7 +24,7 @@ inline void range_check(iterator begin, iterator end, size_t read_size)
}
}
// @returnss the next iterator position
// @returns the next iterator position
template<typename T>
iterator read(iterator, iterator, T&,
typename enable_if< std::is_floating_point<T> >::type* = 0)
......
......@@ -138,7 +138,7 @@ class post_office_worker
return m_parent;
}
// @returnss new reference count
// @returns new reference count
size_t parent_exited(native_socket_t parent_socket)
{
if (has_parent() && parent() == parent_socket)
......@@ -230,7 +230,7 @@ class po_peer : public post_office_worker
}
}
// @returnss false if an error occured; otherwise true
// @returns false if an error occured; otherwise true
bool read_and_continue()
{
switch (m_state)
......@@ -381,7 +381,7 @@ class po_doorman : public post_office_worker
{
}
// @returnss false if an error occured; otherwise true
// @returns false if an error occured; otherwise true
bool read_and_continue()
{
sockaddr addr;
......
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