LCM
List of all members | Public Types | Public Member Functions
lcm::LCM Class Reference

Core communications class for the C++ API. More...

#include <lcm/lcm-cpp.hpp>

Public Types

template<class MessageType >
using HandlerFunction = std::function< void(const ReceiveBuffer *rbuf, const std::string &channel, const MessageType *msg)>
 

Public Member Functions

 LCM (std::string lcm_url="")
 Constructor. More...
 
 LCM (lcm_t *lcm_in)
 Constructor. More...
 
 ~LCM ()
 Destructor. More...
 
bool good () const
 Checks if initialization succeeded during object construction. More...
 
int publish (const std::string &channel, const void *data, unsigned int datalen)
 Publishes a raw data message. More...
 
template<class MessageType >
int publish (const std::string &channel, const MessageType *msg)
 Publishes a message with automatic message encoding. More...
 
int getFileno ()
 Returns a file descriptor or socket that can be used with select(), poll(), or other event loops for asynchronous notification of incoming messages. More...
 
int handle ()
 Waits for and dispatches messages. More...
 
int handleTimeout (int timeout_millis)
 Waits for and dispatches messages, with a timeout. More...
 
template<class MessageType , class MessageHandlerClass >
Subscriptionsubscribe (const std::string &channel, void(MessageHandlerClass::*handlerMethod)(const ReceiveBuffer *rbuf, const std::string &channel, const MessageType *msg), MessageHandlerClass *handler)
 Subscribes a callback method of an object to a channel, with automatic message decoding. More...
 
template<class MessageHandlerClass >
Subscriptionsubscribe (const std::string &channel, void(MessageHandlerClass::*handlerMethod)(const ReceiveBuffer *rbuf, const std::string &channel), MessageHandlerClass *handler)
 Subscribe a callback method of an object to a channel, without automatic message decoding. More...
 
template<class MessageType , class ContextClass >
SubscriptionsubscribeFunction (const std::string &channel, void(*handler)(const ReceiveBuffer *rbuf, const std::string &channel, const MessageType *msg, ContextClass context), ContextClass context)
 Subscribe a function callback to a channel, with automatic message decoding. More...
 
template<class ContextClass >
SubscriptionsubscribeFunction (const std::string &channel, void(*handler)(const ReceiveBuffer *rbuf, const std::string &channel, ContextClass context), ContextClass context)
 Subscribe a function callback to a channel, without automatic message decoding. More...
 
template<class MessageType >
Subscriptionsubscribe (const std::string &channel, HandlerFunction< MessageType > handler)
 Subscribes a callback function to a channel, with automatic message decoding. More...
 
int unsubscribe (Subscription *subscription)
 Unsubscribes a message handler. More...
 
lcm_tgetUnderlyingLCM ()
 retrives the lcm_t C data structure wrapped by this class. More...
 

Detailed Description

Core communications class for the C++ API.

Member Typedef Documentation

◆ HandlerFunction

template<class MessageType >
using lcm::LCM::HandlerFunction = std::function<void(const ReceiveBuffer *rbuf, const std::string &channel, const MessageType *msg)>

Type alias for the handler function type.

Constructor & Destructor Documentation

◆ LCM() [1/2]

lcm::LCM::LCM ( std::string  lcm_url = "")
inline

Constructor.

Initializes the LCM instance and connects it to the specified LCM network. See the documentation on lcm_create() in the C API for details on how lcm_url is formatted.

See also
lcm_create()

◆ LCM() [2/2]

lcm::LCM::LCM ( lcm_t lcm_in)
inline

Constructor.

Initializes the c++ LCM instance from an existing C instance.

See also
lcm_create()

◆ ~LCM()

lcm::LCM::~LCM ( )
inline

Destructor.

Disconnects from the LCM network, and destroys all outstanding Subscription objects.

Member Function Documentation

◆ getFileno()

int lcm::LCM::getFileno ( )
inline

Returns a file descriptor or socket that can be used with select(), poll(), or other event loops for asynchronous notification of incoming messages.

This method is useful when integrating LCM into another event loop, such as the Qt event loop (via QSocketNotifier), the GLib event loop (via GIOChannel), a custom select() - or poll() -based event loop, or any other event loop that supports file descriptors.

Todo:
link to example code.
Returns
a non-negative file descriptor on success, or -1 if something is wrong.
See also
lcm_get_fileno()

◆ getUnderlyingLCM()

lcm_t* lcm::LCM::getUnderlyingLCM ( )
inline

retrives the lcm_t C data structure wrapped by this class.

This method should be used carefully and sparingly. An example use case would be extending the subscription mechanism to Boost Function objects.

Returns
the lcm_t instance wrapped by this object.
See also
lcm_t

◆ good()

bool lcm::LCM::good ( ) const
inline

Checks if initialization succeeded during object construction.

Returns
true if initialization succeeded and the instance appears ready for communication, false if not.

◆ handle()

int lcm::LCM::handle ( )
inline

Waits for and dispatches messages.

Returns
0 on success, -1 if something went wrong.
See also
lcm_handle()

◆ handleTimeout()

int lcm::LCM::handleTimeout ( int  timeout_millis)
inline

Waits for and dispatches messages, with a timeout.

New in LCM 1.1.0.

Returns
>0 if a message was handled, 0 if the function timed out, and <0 if an error occured.
See also
lcm_handle_timeout()

◆ publish() [1/2]

template<class MessageType >
int lcm::LCM::publish ( const std::string &  channel,
const MessageType *  msg 
)
inline

Publishes a message with automatic message encoding.

This template method is designed for use with C++ classes generated by lcm-gen.

Parameters
channelthe channel to publish the message on.
msgthe message to publish.
Returns
0 on success, -1 on failure.

◆ publish() [2/2]

int lcm::LCM::publish ( const std::string &  channel,
const void *  data,
unsigned int  datalen 
)
inline

Publishes a raw data message.

Parameters
channelthe channel to publish the message on.
datadata buffer containing the message to publish
datalenlength of the message, in bytes.
Returns
0 on success, -1 on failure.

◆ subscribe() [1/3]

template<class MessageType >
Subscription* lcm::LCM::subscribe ( const std::string &  channel,
HandlerFunction< MessageType >  handler 
)

Subscribes a callback function to a channel, with automatic message decoding.

This method is designed for use with C++ classes generated by lcm-gen .

The callback function will be invoked on the object when a message arrives on the specified channel. Prior to method invocation, LCM will attempt to automatically decode the message to the specified message type MessageType , which should be a class generated by lcm-gen . If message decoding fails, the callback function is not invoked and an error message is printed to stderr.

The callback function is invoked during calls to LCM::handle(). Callback methods are invoked by the same thread that invokes LCM::handle(), in the order that they were subscribed.

For example:

#include <exlcm/example_t.lcm>
#include <lcm/lcm-cpp.hpp>
int main(int argc, char** argv) {
lcm::LCM lcm;
func = [](const lcm::ReceiveBuffer* rbuf, const std::string& channel,
const exlcm::example_t* msg) {
// do something with the message
}
lcm.subscribe("CHANNEL", func);
while(true)
lcm.handle();
return 0;
}
Core communications class for the C++ API.
Definition: lcm-cpp.hpp:44
Subscription * subscribe(const std::string &channel, void(MessageHandlerClass::*handlerMethod)(const ReceiveBuffer *rbuf, const std::string &channel, const MessageType *msg), MessageHandlerClass *handler)
Subscribes a callback method of an object to a channel, with automatic message decoding.
int handle()
Waits for and dispatches messages.
std::function< void(const ReceiveBuffer *rbuf, const std::string &channel, const MessageType *msg)> HandlerFunction
Definition: lcm-cpp.hpp:377
Stores the raw bytes and timestamp of a received message.
Definition: lcm-cpp.hpp:471
Parameters
channelThe channel to subscribe to. This is treated as a regular expression implicitly surrounded by '^' and '$'.
handlerA handler function, for example a lambda.
Returns
a Subscription object that can be used to adjust the subscription and unsubscribe. The Subscription object is managed by the LCM class, and is automatically destroyed when its LCM instance is destroyed.

◆ subscribe() [2/3]

template<class MessageHandlerClass >
Subscription* lcm::LCM::subscribe ( const std::string &  channel,
void(MessageHandlerClass::*)(const ReceiveBuffer *rbuf, const std::string &channel)  handlerMethod,
MessageHandlerClass *  handler 
)

Subscribe a callback method of an object to a channel, without automatic message decoding.

This method is designed for use when automatic message decoding is not desired.

The callback method will be invoked on the object when a message arrives on the specified channel. Callback methods are invoked during calls to LCM::handle(), by the same thread that calls LCM::handle(). Callbacks are invoked in the order that they were subscribed.

For example:

#include <lcm/lcm-cpp.hpp>
class MyMessageHandler {
void onMessage(const lcm::ReceiveBuffer* rbuf, const std::string& channel) {
// do something with the message. Raw message bytes are
// accessible via rbuf->data
}
};
int main(int argc, char** argv) {
lcm::LCM lcm;
MyMessageHandler handler;
lcm.subscribe("CHANNEL", &MyMessageHandler::onMessage, &handler);
while(true)
lcm.handle();
return 0;
}
Parameters
channelThe channel to subscribe to. This is treated as a regular expression implicitly surrounded by '^' and '$'.
handlerMethodA class method pointer identifying the callback method.
handlerA class instance that the callback method will be invoked on.
Returns
a Subscription object that can be used to adjust the subscription and unsubscribe. The Subscription object is managed by the LCM class, and is automatically destroyed when its LCM instance is destroyed.

◆ subscribe() [3/3]

template<class MessageType , class MessageHandlerClass >
Subscription* lcm::LCM::subscribe ( const std::string &  channel,
void(MessageHandlerClass::*)(const ReceiveBuffer *rbuf, const std::string &channel, const MessageType *msg)  handlerMethod,
MessageHandlerClass *  handler 
)

Subscribes a callback method of an object to a channel, with automatic message decoding.

This method is designed for use with C++ classes generated by lcm-gen .

The callback method will be invoked on the object when a message arrives on the specified channel. Prior to method invocation, LCM will attempt to automatically decode the message to the specified message type MessageType , which should be a class generated by lcm-gen . If message decoding fails, the callback method is not invoked and an error message is printed to stderr.

The callback method is invoked during calls to LCM::handle(). Callback methods are invoked by the same thread that invokes LCM::handle(), in the order that they were subscribed.

For example:

#include <exlcm/example_t.lcm>
#include <lcm/lcm-cpp.hpp>
class MyMessageHandler {
void onMessage(const lcm::ReceiveBuffer* rbuf, const std::string& channel,
const exlcm::example_t* msg) {
// do something with the message
}
};
int main(int argc, char** argv) {
lcm::LCM lcm;
MyMessageHandler handler;
lcm.subscribe("CHANNEL", &MyMessageHandler::onMessage, &handler);
while(true)
lcm.handle();
return 0;
}
Parameters
channelThe channel to subscribe to. This is treated as a regular expression implicitly surrounded by '^' and '$'.
handlerMethodA class method pointer identifying the callback method.
handlerA class instance that the callback method will be invoked on.
Returns
a Subscription object that can be used to adjust the subscription and unsubscribe. The Subscription object is managed by the LCM class, and is automatically destroyed when its LCM instance is destroyed.

◆ subscribeFunction() [1/2]

template<class MessageType , class ContextClass >
Subscription* lcm::LCM::subscribeFunction ( const std::string &  channel,
void(*)(const ReceiveBuffer *rbuf, const std::string &channel, const MessageType *msg, ContextClass context)  handler,
ContextClass  context 
)

Subscribe a function callback to a channel, with automatic message decoding.

This method is designed for use with static member functions and C-style functions.

The callback function will be invoked on the object when a message arrives on the specified channel. Prior to callback invocation, LCM will attempt to automatically decode the message to the specified message type MessageType , which should be a class generated by lcm-gen . If message decoding fails, the callback function is not invoked and an error message is printed to stderr.

The callback function is invoked during calls to LCM::handle(). Callbacks are invoked by the same thread that invokes LCM::handle(), in the order that they were subscribed.

For example:

#include <lcm/lcm-cpp.hpp>
class State {
public:
lcm::LCM lcm;
int usefulVariable;
};
void onMessage(const lcm::ReceiveBuffer* rbuf, const std::string& channel, const MessageType*
msg, State* state) {
// do something with the message.
}
int main(int argc, char** argv) {
State* state = new State;
state->lcm.subscribe("CHANNEL", onMessage, state);
while(true)
state->lcm.handle();
delete state;
return 0;
}
Parameters
channelThe channel to subscribe to. This is treated as a regular expression implicitly surrounded by '^' and '$'.
handlerA function pointer identifying the callback function.
contextA context variable that will be passed to the callback function. This can be used to pass state or other information to the callback function. If not needed, then ContextClass can be set to void*, and this argument set to NULL.
Returns
a Subscription object that can be used to adjust the subscription and unsubscribe. The Subscription object is managed by the LCM class, and is automatically destroyed when its LCM instance is destroyed.

◆ subscribeFunction() [2/2]

template<class ContextClass >
Subscription* lcm::LCM::subscribeFunction ( const std::string &  channel,
void(*)(const ReceiveBuffer *rbuf, const std::string &channel, ContextClass context)  handler,
ContextClass  context 
)

Subscribe a function callback to a channel, without automatic message decoding.

This method is designed for use when automatic message decoding is not desired.

For example:

#include <lcm/lcm-cpp.hpp>
void onMessage(const lcm::ReceiveBuffer* rbuf, const std::string& channel, void*) {
// do something with the message. Raw message bytes are
// accessible via rbuf->data
}
int main(int argc, char** argv) {
LCM::lcm lcm;
lcm.subscribe("CHANNEL", onMessage, NULL);
while(true)
lcm.handle();
return 0;
}
Parameters
channelThe channel to subscribe to. This is treated as a regular expression implicitly surrounded by '^' and '$'.
handlerA function pointer identifying the callback function.
contextA context variable that will be passed to the callback function. This can be used to pass state or other information to the callback function. If not needed, then ContextClass can be set to void*, and this argument set to NULL.
Returns
a Subscription object that can be used to adjust the subscription and unsubscribe. The Subscription object is managed by the LCM class, and is automatically destroyed when its LCM instance is destroyed.

◆ unsubscribe()

int lcm::LCM::unsubscribe ( Subscription subscription)
inline

Unsubscribes a message handler.

After unsubscription, the callback registered by the original call to subscribe() or subscribeFunction() will no longer be invoked when messages are received. The Subscription object is destroyed by this method.

Parameters
subscriptiona Subscription object previously returned by a call to subscribe() or subscribeFunction().
Returns
0 on success, -1 if subscription is not a valid subscription.

The documentation for this class was generated from the following file: