PX4（PIXHAWK）源码开发人员文档（三）——进程间通讯的开发者指南

/* declare the topic */
ORB_DECLARE(random_integer);
/* define the data structure that will be published where subscribers cansee it */
struct random_integer_data{
          int r;
};

#include <topic.h>
 /* create topic metadata */
ORB_DEFINE(random_integer); 
/* file handle that will be used for publishing */
staticint topic_handle; 
int init()
{
          /* generate the initial data for first publication*/
          struct random_integer_data rd={ .r= random(),};
          /* advertise the topic and make the initialpublication */
          topic_handle = orb_advertise(ORB_ID(random_integer),&rd);
}
int update_topic()
{
          /* generate a new random number forpublication */
          struct random_integer_data rd={ .r= random(),};
          /* publish the new data structure */
          orb_publish(ORB_ID(random_integer), topic_handle,&rd);
}

#include <topic.h>
 /* file handle that will be used forsubscribing */
staticint topic_handle;
int init()
{
          /* subscribe to the topic */
          topic_handle = orb_subscribe(ORB_ID(random_integer));
}
 voidcheck_topic()
{
          bool updated;
          struct random_integer_data rd; 
          /* check to see whether the topic has updatedsince the last time we read it */
          orb_check(topic_handle,&updated);
          if(updated){
                    /* make a local copy of the updated datastructure */
                    orb_copy(ORB_ID(random_integer), topic_handle,&rd);
                    printf("Random integer is now %d\n", rd.r);
          }
}

/**
 * Advertise as the publisher of atopic.
 *
 * This performs the initialadvertisement of a topic; it creates the topic
 * node in /obj if required andwrites the initial data.
 *
 * @param meta                 The uORB metadata (usually fromthe ORB_ID() macro)
 *                             forthe topic. topic uORB元数据（通常来自ORB_ID()宏）
 * @param data                 A pointer to the initial datato be published.指向将要publish初始数据的指针。
 *                             Fortopics published by interrupt handlers, the advertisement
 *                             mustbe performed from non-interrupt context.
 * @return           ERROR on error, otherwise returns a handle
 *                             thatcan be used to publish to the topic.
 *                             Ifthe topic in question is not known (due to an
 *                             ORB_DEFINE_OPTIONALwith no corresponding ORB_DECLARE)
 *                             thisfunction will return -1 and set errno to ENOENT.
 */
externint          orb_advertise(conststruct orb_metadata *meta,constvoid*data);

/**
 * Publish new data to a topic.
 *
 * The data is atomically publishedto the topic and any waiting subscribers
 * will be notified.  Subscribers that are not waiting can checkthe topic
 * for updates using orb_checkand/or orb_stat.
 *
 * @handle           The handle returned from orb_advertise.
 * @param meta                 The uORB metadata (usually fromthe ORB() macro)
 *                             forthe topic.
 * @param data                 A pointer to the data to bepublished.
 * @return           OK on success, ERROR otherwise with errno set accordingly.
 */
externint          orb_publish(conststruct orb_metadata *meta,int handle,constvoid*data);

/**
 * Subscribe to a topic.
 *
 * The returned value is a filedescriptor that can be passed to poll()
 * in order to wait for updates to atopic, as well as orb_read,
 * orb_check and orb_stat.
 *
 * Subscription will succeed even ifthe topic has not been advertised;
 * in this case the topic will havea timestamp of zero, it will never
 * signal a poll() event, checkingwill always return false and it cannot
 * be copied. When the topic issubsequently advertised, poll, check,
 * stat and copy calls will react tothe initial publication that is
 * performed as part of theadvertisement.
 *
 * Subscription will fail if thetopic is not known to the system, i.e.
 * there is nothing in the systemthat has defined the topic and thus it
 * can never be published.
 *
 * @param meta                 The uORB metadata (usually fromthe ORB_ID() macro)
 *                             forthe topic.
 * @return           ERROR on error, otherwise returns a handle
 *                             thatcan be used to read and check the topic for updates.
 *                             Ifthe topic in question is not known (due to an
 *                             ORB_DEFINE_OPTIONALwith no corresponding ORB_DECLARE)
 *                             thisfunction will return -1 and set errno to ENOENT.
 */
externint          orb_subscribe(conststruct orb_metadata *meta);

/**
 * Unsubscribe from a topic.
 *
 * @param handle     A handle returned from orb_subscribe.
 * @return           OK on success, ERROR otherwise with errno set accordingly.
 */
externint          orb_unsubscribe(int handle);

/**
 * Fetch data from a topic.
 *
 * @param meta                 The uORB metadata (usually fromthe ORB() macro)
 *                             forthe topic.
 * @param handle     A handle returned from orb_subscribe.
 * @param buffer     Pointer to the buffer receiving the data.
 * @return           OK on success, ERROR otherwise with errno set accordingly.
 */
externint          orb_copy(conststruct orb_metadata *meta,int handle,void*buffer);

/**
 * Check whether a topic has beenpublished to since the last orb_copy.
 *
 * This check can be used todetermine whether to copy from the topic when
 * not using poll(), or to avoid theoverhead of calling poll() when the
 * topic is likely to have updated.
 *
 * Updates are tracked on aper-handle basis; this call will continue to
 * return true until orb_copy iscalled using the same handle. This interface
 * should be preferred over callingorb_stat due to the race window between
 * stat and copy that can lead tomissed updates.
 *
 * @param handle     A handle returned from orb_subscribe.
 * @param updated    Set to true if the topic has been publishedsince the
 *                             lasttime it was copied using this handle.
 * @return           OK if the check was successful, ERROR otherwise with
 *                             errnoset accordingly.
 */
externint          orb_check(int handle, bool *updated);

/**
 * Return the last time that thetopic was published.
 *
 * @param handle     A handle returned from orb_subscribe.
 * @param time                 Returns the time that the topicwas published, or zero if it has
 *                             neverbeen published/advertised.
 * @return           OK on success, ERROR otherwise with errno set accordingly.
 */
externint          orb_stat(int handle,uint64_t*time);

ORB_DECLARE(color_red);
ORB_DECLARE(color_green);
ORB_DECLARE(color_blue);
ORB_DECLARE(color_timeouts);
 
/* structure published to color_red, color_green, color_blue andcolor_timeouts */
struct color_update
{
          int number;
};
color_counter.c
#include <poll.h>
 
ORB_DEFINE(color_timeouts,struct color_update);
 
void
subscriber(void)
{
          int       sub_red, sub_green, sub_blue;
          int       pub_timeouts;
          int       timeouts=0;
          struct color_update cu;
 
          /* subscribe to color topics */
          sub_red = orb_subscribe(ORB_ID(color_red));
          sub_green = orb_subscribe(ORB_ID(color_green));
          sub_blue = orb_subscribe(ORB_ID(color_blue));
 
          /* advertise the timeout topic */
          cu.number=0;
          pub_timeouts = orb_advertise(ORB_ID(color_timeouts),&cu);
 
          /* loop waiting for updates */
          for(;;){
 
                    /* wait for updates or a 1-second timeout */
                    struct pollfd fds[3]={
                               { .fd= sub_red,   .events= POLLIN },
                               { .fd= sub_green, .events= POLLIN },
                               { .fd= sub_blue,  .events= POLLIN }
                    };
                    int ret= poll(fds,3,1000);
 
                    /* check for a timeout */
                    if(ret==0){
                               puts("timeout");
                               cu.number=++timeouts;
                               orb_publish(ORB_ID(color_timeouts), pub_timeouts,&cu);
 
                    /* check for color updates */
                    }else{
 
                               if(fds[0].revents& POLLIN){
                                         orb_copy(ORB_ID(color_red), sub_red,&cu);
                                        printf("red is now %d\n", cu.number);
                               }
                               if(fds[1].revents& POLLIN){
                                         orb_copy(ORB_ID(color_green), sub_green,&cu);
                                        printf("green is now %d\n", cu.number);
                               }
                               if(fds[2].revents& POLLIN){
                                         orb_copy(ORB_ID(color_blue), sub_blue,&cu);
                                        printf("blue is now %d\n", cu.number);
                               }
                    }
          }
}

/**
 * Set the minimum interval betweenwhich updates are seen for a subscription.
 *
 * If this interval is set, thesubscriber will not see more than one update
 * within the period.
 *
 * Specifically, the first time anupdate is reported to the subscriber a timer
 * is started. The update willcontinue to be reported via poll and orb_check, but
 * once fetched via orb_copy anotherupdate will not be reported until the timer
 * expires.
 *
 * This feature can be used to pacea subscriber that is watching a topic that
 * would otherwise update tooquickly.
 *
 * @param handle     A handle returned from orb_subscribe.
 * @param interval   An interval period in milliseconds.
 * @return           OK on success, ERROR otherwise with ERRNO set accordingly.
 */
externint          orb_set_interval(int handle,unsigned interval);